Documentation framework
Documentation for Plash has gone through several phases:
- Initially it was done in Docbook. Docbook has the advantage that it can output to HTML and to man pages (and theoretically other formats though I didn't try those). The downsides are:
- Docbook is very complicated. The tag names are long. It is not convenient to enter by hand, and I haven't found a good XML editor.
- It took a long time to run the conversion when I was using it. It doesn't work incrementally.
- I switched to using mostly HTML tags, but with a different surface tag syntax from XML which was supposed to be easier to enter.
- This did not have the ability to generate man pages (i.e. nroff/groff format), which I left in Docbook format. I have not found a converter from HTML (or any simple XML format) to man page format yet.
- Switched to a Moinmoin wiki (the current system).
Advantages of the wiki:
- Instant feedback: you see the page as it appears to others immediately after editing it. Similarly, when editing, you navigate to pages the way others do. This contrasts with editing in Emacs where you must find the page to edit separately from what is displayed in the Web browser.
It is versioned separately from the source code, which is good for development/planning notes (such as RoadMap).
- It can be edited from anywhere.
The current wiki has some problems:
- Data is not managed by a proper version control system, but by Moinmoin's ad-hoc versioning system.
- Pages are not organised into a tree.
Navigation and summary information must be duplicated across pages. For example, FrontPage contains one-line summaries of the pages it links to.
- There is no good way to convert to static pages. Ideally want to be able to produce multi-page HTML, single-page HTML and printable output.
- Access control and branching: ideally, would allow new users to create a branch and make changes to that, rather than editing the main visible wiki directly.
Alternatively, provide the ability to comment on documentation. See the Postgresql docs for an example of this.
- No framework for embedding code into documentation that gets run as a test (like doctests).
Some documentation needs to get maintained as part of the source code:
- Documentation for method interfaces
- Documentation with executable, automatically-tested example code
Feature matrix
System |
Quick feedback |
Man pages |
Editable offline |
Branchable |
Docbook |
no |
|
|
|
Ad-hoc HTML |
no |
no |
|
|
Moinmoin wiki |
|
no |
no |
no |
Desired features
- Store documentation in XML format, but convert to/from a more readable wiki-style format for the purposes of editing. This would allow the wiki system to support multiple surface syntaxes.
DocBook Wiki does this
Can use an HTML to Markdown converter to implement this. There are multiple implementations around including html2text (written in Python)
- Support branches. New users initially only get the ability to make changes to their own branch (though these can be viewable by everyone).
Have a table-of-contents page which lists all pages in the wiki, providing a tree structure. This furnishes each page with a parent and an ordered list of children. A wiki lint tool can provide warnings about pages that are not hooked into the table of contents. The lint tool can be run by ContinuousIntegration.
- Divide the wiki into "documentation" and "planning" sections. "Planning" covers workflow: bugs and new features. Perhaps have a colour-coding scheme. These classifications would be orthogonal to the table of contents' hierarchy.
Ikiwiki
Ikiwiki decouples editing pages from generating HTML output. The two parts communicate via an SCM repository. The generated HTML needs to be able to link back to the editor telling it which file to edit.
See Ikiwiki.
Other projects
The Coyotos project has also been looking for a system to manage documentation: http://dev.eros-os.com/content/we-don-039-t-need-no-stinking-architecture
Ville-Pekka Vainio had a project to import man pages into a wiki to edit while allowing changes to be submitted back upstream.
Tasks
- Find a good way to generate man pages. Current man pages are generated from Docbook.
- I have found two bits of code that generate man pages from Docbook on Ubuntu: docbook2x and docbook-to-man
- Experiment with Ikiwiki