Difference between revisions of "Google Season of Docs 2022/Organize and Update Apertium User Documentation"
Popcorndude (talk | contribs) |
Popcorndude (talk | contribs) |
||
Line 133: | Line 133: | ||
| Single canonical source containing existing info |
| Single canonical source containing existing info |
||
|- |
|- |
||
− | | Weeks 2- |
+ | | Weeks 2-4 |
− | May 8- |
+ | May 8-28 |
| Fill in gaps in formal docs |
| Fill in gaps in formal docs |
||
| |
| |
||
Line 145: | Line 145: | ||
| |
| |
||
|- |
|- |
||
− | | Weeks |
+ | | Weeks 5-7 |
− | May |
+ | May 29-June 18 |
| Dictionary tutorials |
| Dictionary tutorials |
||
| |
| |
||
Line 155: | Line 155: | ||
| Information sufficient to get a beginner set up and contributing to lexicons |
| Information sufficient to get a beginner set up and contributing to lexicons |
||
|- |
|- |
||
− | | Weeks |
+ | | Weeks 8-10 |
− | June |
+ | June 19-July 2 |
| Transfer tutorials |
| Transfer tutorials |
||
| |
| |
||
Line 162: | Line 162: | ||
| Systematic tutorial for writing transfer rules |
| Systematic tutorial for writing transfer rules |
||
|- |
|- |
||
− | | Weeks |
+ | | Weeks 11-13 |
+ | July 3-23 |
||
− | June 19-July 2 |
||
| Other tutorials |
| Other tutorials |
||
| |
| |
||
Line 178: | Line 178: | ||
| |
| |
||
|- |
|- |
||
− | | |
+ | | Weeks 14-15 |
− | July |
+ | July 24-August 6 |
| Theoretical background |
| Theoretical background |
||
| |
| |
||
Line 191: | Line 191: | ||
| |
| |
||
| |
| |
||
+ | |- |
||
+ | | Weeks 16-18 |
||
+ | August 7-27 |
||
+ | | How-to and code |
||
+ | | |
||
+ | * A few how-to guides and make it easy to add more |
||
+ | * For each core repo: |
||
+ | ** Document listing the general purpose of each source file |
||
+ | ** Doc-comment for each noteworthy function |
||
+ | ** Outline of the operation and control flow of each class corresponding to an executable |
||
+ | | Guidelines for contributing to the code |
||
|} |
|} |
||
Revision as of 23:31, 23 March 2022
Contents
About Apertium
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 create updated documentation for all pipeline modules and/or a full tutorial.
Ideally documentation on a given tool will exist in a single place, and a full tutorial will also have a single unified source. One possibility is to generate one set of docs from another, or from a single unified source. For example, if we want tools to be documented in both their GitHub repos and on the wiki, we should generate one set of documentation from the other (or a third source). If we want a full tutorial to be on the wiki but also available in PDF format, then we should designate one source as the original and generate the others from them.
The scope
- Overview of the Apertium platform
- All stages of the Apertium pipeline
- The main approaches to and tools for each stage
Measuring success
Existing Documentation
Formal Descriptions
Source | Mostly Complete | Partial |
---|---|---|
2.0 docs |
|
|
wiki |
|
|
github |
|
|
external sources |
|
missing:
- build scripts (filter-rules, etc)
- spellchecker
- postgenerator?
Tutorials
Even things in the "substantive" column will likely need a fair amount of work for the purposes of this project.
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 |