On the forums, brokebit asks “where is documentation posted?”  A timely question, because this week we’ve spent some time planning what documentation we hope to deliver for the upcoming 1.6 release.

In the past our documentation process as looked somewhat like this: Our developers jot down some notes in various places, and with luck we get them to post those notes to our internal wiki. Over time use of the wiki has generally improved so there is pretty good information there now. We use MediaWiki, which in our setup is basically impossible to search. So finding the documentation is hard. But that’s a topic for another day!

So, when it comes time for the actual commercial release, we’ve got a bunch of good resources lying around. We have one of our business analysts  compile all of this information and hand it off to a consultant that does our training materials (we have an extensive training program for our resellers and customers) for him to compile into a complete package.

In the meantime, our open source release has a text file containing some basic installation instructions. So this is where John and I are focusing our efforts for the next release. Vicente Cano, our build master, has proposed that we try to ship 1.6 with the following documents:

• Installation Guide
• Admin Guide
• User Guide
  

We haven’t quite hashed out exactly what these will contain or what they will look like. We have been looking to Splunk, MySQL, Apache HTTP, and the Linux From Scratch Project for inspiration, but any feedback on our ideas would be appreciated.

Even while we’re trying to figure out what we’re going to publish we need to figure out how we’re going to create the material. Our entire company is very focused on getting our commercial release out the door and we don’t have a lot of time to expend on open source documentation. This means that we need to be able to collect information from as many people as possible in a very lightweight manner.

Getting our developers to write little bits of documentation on the parts of the software they have written is potentially doable. If we were to ask for this we would have to first determine what format we wanted them to write in. They are already familiar with Microsoft Word. Word is what we use to compile our commercial documentation. I think that Word is by far the best writing tool our industry has to offer. It has incredible change tracking tools, grammar correction, and all the other drafting tools a technical writer could dream of.

Unfortunately, it is extremely bad karma to develop open source software documentation in Word—I don’t know if I could sleep at night if we committed such files to our repo. My main problem with Word files is that they are binary (even the new WordML is saved as a ZIP archive) so proper SVN diffs are impossible. They are also unstructured, so combining them into a nicely organized book is sort of an inexact science of various style combinations. You also can’t use Word files for single-sourcing very effectively.

For the long term Vicente and I generally think that DocBook is our best bet. DocBook is an open standard, supports structured documentation and single-sourcing, and has good transformation tools for HTML and PDF. The major downside is that pure DocBook has a steep learning curve. The ideal solution would be to find a good tool for Microsoft Word to DocBook round-tripping. I’ve looked long and hard and I haven’t found any really good solutions. There are some good DocBook editors out there, but any editor is going to have a learning curve and will not be as full-featured as Word.

So we haven’t fully solved this problem. In the meantime I think that we’ll have people write in text format. They can draft in Word if they want but since we’ll have to commit something reasonable to the repo it might as well be text. To make it a bit easier, we can use AsciiDoc, a text markup similar to StructuredText. This will allow developers to write in a very natural format that can eventually be converted over to DocBook when we move further in that direction.


As a final note, I found a short article about how non-programmers use documentation that seems very insightful. I would be interested in any feedback as to what sort of documentation our fledgling community is interested in.