How we maintain documentation

7 | published by Aleksey Bobkov on Wednesday, August 04, 2010

From the beginning we understood that documentation is an important part of LemonStand. For software products which involve scripting, documentation is as significant as the product itself. That is why we started to look for suitable documentation tools from the earliest days of LemonStand.

Third-party tools

We decided to use a Wiki system, because it is flexible and allows us to maintain any documentation structure. Before we came to the current solution we tried different Wiki tools, like PBworks and Media Wiki. Media Wiki is an engine which is used by Wikipedia. We abandoned this engine very early, because it implies editing content using special tags, not in WYSIWYG mode.

In the beginning PBworks had us pretty excited. It's a really great Wiki engine with a beautiful user interface. It's inspiring and simple. I wrote many pages of documentation in PBworks when I started to realize that, unfortunately, PBworks does not satisfy all our needs. The key requirement for LemonStand documentation is displaying code examples. It is very difficult to edit code examples in a WYSIWYG editor. I also found that on occasion PBworks would break code examples when I would switch from read to edit mode.

Drinking our own lemonade

And then I decided to develop our own Wiki. We have a very flexible CMS engine, and can implement any functionality that we may need. The requirements for LemonStand's documentation Wiki were:

WYSIWYG editing
simple code examples editing
easy linking
automatic TOC and sub-TOC generating
search, including the code examples
commenting feature
general simplicity and productivity

I was even surprised by how many things were already done in LemonStand. It only took a few days to develop and implement the Wiki module for LemonStand. Now we have a Wiki module which can display pages, TOCs and code examples. We can edit any page or create a new page using special links below a Wiki article, right from the web site:

The most interesting thing is the code example feature. Editing code examples in WYSIWYG mode is not very efficient. Instead, I developed special tags which we use when we need to include code examples on a page:

wiki_source_block(post_function_example, Post function example, php)

The Wiki recognizes these tags and when I click the Edit code examples link on the Wiki page, it displays a page with a code editor with the syntax highlighter for each code block defined on the page.

The new Wiki was a real breakthrough for us! Now it literally takes seconds to create a new page or update code examples. It allows us to efficiently maintain the documentation with our limited resources. This leaves more time for product development and other important things.