Documentation

A key factor of any successful business, documentation is often overlooked. Documentation requires regular effort else it quickly stagnates, becomes outdated and irrelevant. 

A good documentation system can make all the difference since it revolves around the primary asset of any business - information. Recording this information, making it easy to reference or update is the key to a successful documentation system. The scope of documentation also includes popular formats such as wikis and blogs.

In this essay we discuss common pitfalls, requirements of a good documentation system and evaluation of available solutions.

Common Pitfalls

1. Multiple document repositories : There needs to be only one central document repository that is well known and advertised and easily discoverable. This will hold the entire documents. The moment documents can be either here or there, it leads to confusion and hesitancy to use the system.
2. Complex system : The documentation system itself should be simple to use and as friction-less as possible. A complex system involving many steps will be a deterrent. A simple and quick system is a key to ensure regular usage.

Requirements

1. Self-hosted : While clouds offer a lot of convenience, information is probably better kept closely controlled.
2. WYSIWYG editor : Markdown has its advantages but WYSIWYG is simpler to use. 
3. Support common use-cases : Specially for technical documents, easy lists and code-blocks are essential. So is adding images to documents.
4. Information display : The display of information should be flexible. Pinning of key information areas and chronological display of new material. A predictable hierarchy is useful.

Solutions

1. Ghost : Needs some configuration to get the desired look and feel. Crisp app! The biggest drawback I faced was easily adding code-blocks to lists. It can be done but involves a number of steps. 
2. Wiki.js : Faced the same problem as Ghost. Slightly less crisp.
3. WriteFreely : Excellent for plain text but documents require a little more. For that we need to use markdown.
4. BookStack : Settled for this. Excellent editor and information display. Multiple and flexible information hierarchies. Great permission system. You are reading this essay in BookStack!