A Techie Tech Writer Blog

In the sprawling cacophony of the open source bazaar, tucked away in a quiet corner, there's a little bookshop. What you see from the front is just a few folding tables stacked with some books and pamphlets. You might browse a few, and perhaps pick one up to read later. Take a moment to step inside. Here you find more tables, strewn with paper, pens, and typewriters (hey, we're in a metaphor), where you can pull up a chair and write whatever you like, or edit what some other visitor has written. Best of all, you can take the result and step to the back of the shop, to turn the crank on the mimeograph machine, pushing out pages covered in the intoxicating purple ink of education and revolution.

This changes everything.

This week, through participating in the XO BookSprint, I've become familiar with flossmanuals.net, which provides the infrastructure for the XO and Sugar manuals, and I've met its creator, Adam Hyde. What FLOSS Manuals has done, I've realized, is to take away the technological barriers to creating open source documentation. If you can use a browser and a WYSIWYG editor, you can write and publish documentation for open source projects. All you need to add is the actual content (which is, of course, still non-trivial).

Programmers hate writing documentation. It's #6 out of the Top 10 Things that Annoy Programmers. They'd love it if someone else would take on that task. But programmers on open source projects have a hang-up about only using open source tools. So the word-processing tools that non-programmers are most familiar with, like Microsoft Word or Adobe FrameMaker, are just not acceptable on open source projects. The documentation tools that the open source world has invented tend to be extremely powerful but with obscure syntax and complex workflows, like LaTeX and DocBook XML. You can write documentation using an open source word processor like OpenOffice.org Writer, but you still need a content management system of some kind to handle versioning of drafts and communication within a project community, and CMSs are complex to set up and maintain. And so a divide has emerged, with open source programmers on one side, wishing somebody would come help write the docs, and potential writers on the other side, too intimidated or too busy to learn the tools to work on open source projects.

FLOSS Manuals bridges that divide, and does so in a way that is deeply rooted in the open source ethos of community and collaboration. Flossmanuals.net is based on TWiki, and uses the Xinha WYSIWYG editor for HTML. Because it is a wiki, anyone can create a chapter or a manual, and anyone can edit an existing chapter. However, the maintainer of a manual has control over what changes are ultimately published. I've generally been skeptical of wiki advocates who say, “Oh yeah, and you can create documentation in a wiki, too”, because I've seen very few actual examples. (I've heard that the STC Austin chapter is going to have a presentation about this from someone at Sun, which I'm looking forward to. There's also a group devoted to Wikis for technical documentation at The Content Wrangler Community on Ning.) What's different about the FLOSS Manuals wiki is that it is purpose-built for creating documentation. It's not a case of taking a generic wiki and trying to magically extract documentation from it.

However, a manual on FLOSS Manuals doesn't just live on the wiki. You can take a manual (or a set of chapters selected for your needs), and publish it to HTML or PDF. You can host it on your website, or ship it with your application. You can even “self-publish” it for print-on-demand hard copies through lulu.com. FLOSS Manuals has published a manual for Audacity (audio editing software) this way, and the XO and Sugar manuals will also be available through print-on-demand.

FLOSS Manuals is not the be-all and end-all of open source documentation. The complex, powerful open source doc tools still have a place, as do other alternatives. (I'll post soon about how Sphinx is taking over the Python documentation world.) Flossmanuals.net is heavily oriented towards book-style manuals; you could use it for topic-oriented online help, but it might be a stretch---a HAT it is not. But now that there is FLOSS Manuals, there simply is no longer a technological reason for any open source project not to have documentation.