Wiki Over Documents

Why I don’t like documents

I’ve worked in several companies in the past where documents were the format of choice to document software projects: project start architecture, architecture document, requirements document. I also worked in companies where no documentation was the format of choice :-), but let’s leave that discussion for another day.

Documents have this typical lifecycle:

• Written at a specific moment in time for a specific moment in time: start of a project, a handover, an update
• They are maintained by 1 person, most often
• They are read once by a few people
• They end up being stale (most of the time)

Some people argue that documents are just too static to be used in software projects. I don’t find that to be true. The content of a document is not really static, because changing a document is easy and happens. But the real static nature is the viewpoint from which the document is written. Either it is architecture focussed, requirements focussed, or both, but there is always a sequential order in the documents.

A powerful way of documenting

• Switch the viewpoint to that of the reader
• Connect the dots, do not push that responsibility on to the reader
• The documentation needs to be accessible, do not use an unkown and virtually inaccessible tool for it
• Favor visualization over text. At least, do not write paragraph after paragraph, people do not read! Use colors and bold/italic if you need to write longer paragraphs.
• Especially for software projects: do not document the code… the code is a form of documentation, albeit the least interesting one.

The best way to achieve this and keep it readable/editable for the majority of roles in a software project is using a wiki. Now, even in the wiki space, you have a variety of choices, but most dedicated wiki platforms deliver a decent way to adhere to these principles.

The most tricky principle will probably be the ability to switch around the viewpoint. I have been on the lookout for a tool that could do that for me automagically but haven’t found one yet. The best way to achieve it currently is a combination of a thought-through wiki structure combined with some wiki features such as “/include page”. We need an example to show this, I will do that in a separate post.