Difference between revisions of "Google Season of Docs 2022/Organize and Update Apertium User Documentation"
Popcorndude (talk | contribs) (→Budget) |
(→Budget) |
||
Line 222: | Line 222: | ||
! $6000 |
! $6000 |
||
|} |
|} |
||
+ | |||
+ | We considered adding a $500 "just in case" post, but we can't imagine anything else to cover. We've never paid org mentors, and we don't need to restore from ancient archives or broken hardware - and even if we did, it'd likely be faster to just rewrite that part. |
||
== Additional Information == |
== Additional Information == |
Revision as of 21:27, 24 March 2022
Contents
About Apertium
Apertium (current version 3.6, first release 2004) is a free and open source (mainly GPLv3) rule-based machine translation and language technology platform. We have over 500 languages and pairs, maintained using 15+ different tools.
About the project
The problem
Apertium's wiki and other documentation are out of date, poorly organized, not visible enough, and just plain not user-friendly.
This ranges from documentation of individual tools not reflecting their current state, to our best how-to guides reflecting how things were done a decade ago. Documentation is scattered between the Apertium wiki, individual GitHub repos, an out-of-date pdf "Book", and even published papers and third party sites.
The result is new users and contributors wasting time reading out-of-date materials, and even long-time contributors having no way to be aware of changes to the tools they use.
The solution
The solution to the above problem is to gather the existing documentation and tutorials into a single authoritative source and update them to match the current state of Apertium.
The scope
- Overview of the Apertium platform
- All stages of the Apertium pipeline
- The main approaches to and tools for each stage
Measuring success
Unfortunately, the only metric we have is how many people contact us either via mailing list or IRC, and that number has fallen drastically during the Covid-19 pandemic. But from both feedback and direct questioning, we know contributors (potential and current) manage to find incorrect or outdated documentation.
So the way we would measure success is that the number of contributors somehow winding up following an old tutorial drops close to zero.
Existing Documentation
Formal Descriptions
Source | Mostly Complete | Partial |
---|---|---|
2.0 docs |
|
|
wiki |
|
|
github |
|
|
external sources |
|
missing:
- common build scripts (filter-rules, etc)
- postgenerator?
Tutorials
Source | Substantive | Fragmentary |
---|---|---|
Apertium wiki |
|
|
User:Firespeaker's course wiki |
|
|
missing:
- HFST
- tagger
- separable
Timeline
This follows the 4-part division of https://documentation.divio.com
Time Period | Goal | Details | Deliverable |
---|---|---|---|
Phase 1: Reference | |||
Week 1
May 1-7 |
Gather and convert existing documentation |
|
Single canonical source containing existing info |
Weeks 2-4
May 8-28 |
Fill in gaps in formal docs |
|
Up-to-date formal documentation of main pipeline modules and common build scripts |
Phase 2: Tutorials | |||
Weeks 5-7
May 29-June 18 |
Dictionary tutorials |
|
Information sufficient to get a beginner set up and contributing to lexicons |
Weeks 8-10
June 19-July 2 |
Transfer tutorials |
|
Systematic tutorial for writing transfer rules |
Weeks 11-13
July 3-23 |
Other tutorials |
|
End-to-end tutorial for the translation pipeline |
Phase 3: Explanation | |||
Weeks 14-15
July 24-August 6 |
Theoretical background |
|
Introductions to why Apertium uses the technology that it does |
Phase 4: How-to guides and code structure | |||
Weeks 16-18
August 7-27 |
How-to and code |
|
Guidelines for contributing to the code |
Budget
Budget item | Amount |
---|---|
Paying technical writer | $6000 |
TOTAL: | $6000 |
We considered adding a $500 "just in case" post, but we can't imagine anything else to cover. We've never paid org mentors, and we don't need to restore from ancient archives or broken hardware - and even if we did, it'd likely be faster to just rewrite that part.
Additional Information
Apertium has participated in Google Summer of Code 12 times: 2009, 2010, 2011, 2012, 2013, 2014, 2016, 2017, 2018, 2019, 2020, and 2021.
The technical writer participated in GSoC as a student in 2019 and 2021, and as a mentor in 2020.