So I’ve previously discussed a series of problems Microsoft Word has, and as Josh rightly pointed out, we’re using a tool that wasn’t made for what we’re using it for. 🙂 Thus I began hunting for a new method of writing documentation.
Here were my requirements:
- Must support multiple users editing the same file at the same time.
- Must handle cases where two users edit the same content into two different results. It must do this without crashing or deleting someone’s data.
- Must be able to show me who made a change to the document, exactly what they changed, and when they made it.
- Must be easy to edit by someone who doesn’t make documents for a living. AKA, one of our software devs should be able to make a spec, manual, or test procedure change without having to spend 20 hours in training to learn a tool.
- Must be able to make outlines, align and resize images, tables, and other standard MS Word features.
- Must be able to handle cross-referencing in a clean and friendly way for things like Tables of Contents, Tables of Figures, Indexes, Page Numbers, and Footnotes.
- Cross-referencing must be able to handle local links and not demand a full path.
- Must export to PDF.
Nice to Have:
- Content should be separated from layout and design. I should be able to write text in Notepad, then parse it through a stylesheet and have it format a beautiful PDF for me.
- Content should be able to be exported to PDF, CHM, HTML, DOC, and ODF. LaTeX would also be awesome.
- Look and feel should remain similar across all exported formats.
- I should only have to write one Manual for all of our similar products, then input a code that says “only include content in this manual for versions X and Y”.
- Should be free, both as in beer and as in freedom.
You’d be surprised how hard this hunt was. See links below for more information.
- Adobe FrameMaker: Fails requirements 1 and 4.
- QuarkXPress: Fails #4, but surprisingly handles #1 really nicely.
- DocBook with a CVS: A personal favorite of mine, but it fails requirement 4.
- Scribus: Fails requirements 1 through 4.
- LaTeX with a CVS: Fails requirement 4.
- WIKI: Fails requirement 8. So close and yet so far.
After reviewing all of these heavy hitters, I was dismayed at how many of them would fit my needs if I could remove requirement 4. It was around this time that I discovered my new friend: ReStructuredText.
It uses plain text (.txt) documents that are pushed through a CSS-like stylesheet parser. Outputs to PDF, HTML, LaTeX, and others. I’ve found I like the extra tools available in the RST2PDF extension, as it handles cross-references and 8 1/2 x 11 layout better. Combine this with a standard CVS like SVN or DCVS like Git, and you’ve got an extensible markup language that’s multi-user friendly and easy to learn.
This text file: http://docs.python.org/_sources/whatsnew/2.7.txt
Produces this webpage: http://docs.python.org/whatsnew/2.7.html
I’ll go into more detail about how I’ve set up my RST forge in another post. 🙂