The following outline is from the perspective of a non-doc-committer-committer who wants to see (our good) documentation get 10x better.
Problem Definition
- Docs in FreeBSD is hard^W not (or doesn't appear) easy/simple enough.
- Docs are in XML (DocBook) format. This doesn't suit humans.
- Docs is a separate, repository-specific group of people.
- Lots of apparent or perceived tribal knowledge required.
- Process documented well, but super scary: looks super complex and overwhelming, even to existing committers
Finally:
- First you have to get a commit bit, then you have to become (eventually) a docs committer. Translation: MUST be a docs committer to update docs without a chaperone.
Result / Current State
- Too hard, don't try. New/regular (non-committer) contributors practically nonexistent.
- Even easy stuff/changes don't get submitted
- Bad user outcomes: Docs lag behind current state, often for a very long time
- Burnout: Overburdened docs team
Goals
- Zero-friction documentation authoring/updates. Ideally: Click 'edit', make changes. Save.
- Non-committers submitting high quality docs updates
- Docs issues in Bugzilla processed as well as Ports
Needs
- As simple and easy as possible.
- No unnecessary additional burden on docs/project: Well-maintained, not NIH.
- I don't want to know what latex/docbook/bibliography are. At least not initially
- I want to update/add docs, right now.
- Focus on content not markup: Automatic formatting / validation
- Proper use of docbook/freebsd docs features: Entity/Tag library/completion
- Easy, single step installation: exists or could exist as a port/package
- Ideally improves the OSS ecosystem: OpenSource, if not free for OpenSource / Non-Profit Projects
- Ideally multiple options/alternatives
Perspectives / Concepts
- Docs as changing code. This is the solution is an editor + svn integration perspective. Checkout, launch program, edit, save, commit.
- Docs as content editing. This is the solution is a wiki/service perspective. View, edit, save.
Tooling
Editors
| Name | Language | OpenSource | Free for OSS | Windows | Mac | Linux | FreeBSD | Port{s,able} | DocBook Support |
| oXygen DocBook Editor | Java | ✘ | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | 4, 5, ?? |
| XMLmind DocBook Editor | Java | ✘ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | 4, 5, 5.1 |
| LyX | C++, Python, QT | ✔ | N/A | ✔ | ✔ | ✔ | ✔ | print/lyx | ?? |
Applications
| Name | Language | OpenSource | Free for OSS | DocBook Support |
| XWiki | Java | ✔ | N/A | 4.4 |
See Also
Additional Notes
- Web/App Translation. Mozilla Pontoon: https://github.com/mozilla/pontoon (Production Service)
- Publishing. Mozilla Nucleus: https://github.com/mozilla/nucleus (Websites/Mozilla.org Publishing)