My experiences with writing documentation

Like most developers I don’t like writing documentation. But when I decided to turn Solarium into an opensource project some months ago I really needed to write quite a bit of documentation, because I feel good documentation is very important for an opensource project (actually, for any project…) But there are many ways to document code. I want to share my experiences in finding a solution.

First of all I decided to make good use of phpdoc, a no-brainer. This way I can generate API docs and Phpdoc works great with IDE features like autocompletion and inline documentation.

But API docs alone are not enough, somekind of manual was needed for background info, examples, guidelines etcetera. I’ve seen or worked with multiple solutions in the past, ranging from word docs to wikis, custom websites and docbook. Some were easy to rule out (like Word docs…) but this still left me with several options with their own pros and cons.

I started out by using the wiki option of the GitHub project. The big advantage is that you can enable it with the click of a button and only need to add some content. No hosting, no setup, no development. But after creating several pages I realised there are several drawbacks:

• You are very limited by what the wiki syntax offers, no custom scripts or html allowed
• GitHub wikis don’t support Gists (strangely enough)
• As with most wikis there is no way to create a page hierarchy
• And several other small annoyances

So I started searching for another solution. After some research I ended up with Sphinx or DocBook. Both use markup files for generating docs in multiple formats. I really liked the idea of making the documentation part of the github project files, and exporting into multiple formats.
I tried DocBook. While this looked ideal and the result was ok, editing DocBook was tedious. I could not find a good DocBook WYSIWYG editor, and XML editing is very time consuming. And after editing I needed to ‘build’ the XML into an output format to check the result.

After making little progress I decided this was not the way to go. Writing documentation is never fun, but this was really tedious. So, again, I decided to look for an alternative. This time with ease of use as a top priority. I want to be able to easily write documentation, and anyone else wanting to help should be able to do so without a big learning curve.

The best experiences I had with documenting were with wikis. They allow for easy editting, can be customized and allow for collaborative editing. The biggest drawback of wikis is lack of structure, the pages are only loosely related. In most wikis you need to find your own way by searching for keywords or following links in the content. But besides from that issue, a wiki would be good solution.

So I started with a basic mediawiki install. Added a skin, and some settings to disable several unwanted options. Next, I needed to add some structure for creating a manual. I found the hierarchy extension that seemed ok. It did require some fiddling to get working, but nothing too complicated.
After some testing I found several issues, but I knew I could get it working. With some customization I’ve created a solution that I’m very happy with. You can see the index on the wiki homepage and navigation on all manual pages, like this one.
I think it’s the best of both worlds: I have a structured manual that is easy to maintain, and still have the freedom of a wiki for all other pages.

I did add some other small options to the wiki. The GitHub extension was installed (and slightly modified to support inclusion of a specific gist file) to included Gists, this works much nicer than editing inline code examples. And I created a template for API doc integration. Finally I added the ambox template for nice alerts in the manual.

With the wiki in place the writing of documentation speeded up. For the first time I actually enjoyed writing docs and while writing docs I also came across several issues in the code that I didn’t notice before, similar to how writing unittests can point to design issues. Writing documentation forces you to describe the working of your code in detail, exposing any unlogical parts.

While it still needs more work I think the current result is quite nice, you can see it at http://wiki.solarium-project.org/.