Some time ago I saw an information about new StackOverflow section named Documentation. At the very beginning, I was very excited about this new feature. It sounds great to structure and organizes all the knowledge contained into this portal. Every day thousands of developers contribute to growing this one of the world’s biggest knowledge base. It is a great goal to achieve. However, when I started to look carefully at the content and the form of the knowledge in this documentation I realized that I even don’t know what good documentation means. So I decided to start my journey in search of good documentation.

Why we create documentation?

At first, we have to consider the most important question. Why do we need to bother about documentation? There are two cases:

• writing a library that other developers may use
• developing a regular application

We can easily see the difference between these two variants, but the case of documentation they behave almost the same. If we consider that every part of application code need a maintenance, we can say that we write every project for other developers. In some cases, the other developers would be – we some time later. However generally we can assume that independently from the project purpose, we should store our knowledge. It is important especially if we decide to create some custom components – without following to some standards. That kind of documentation should be a great help when a fresh person wants to use it or modify it. It can be also the first place to search business assumptions used in the project.

Who wants to use documentation and when?

Based on the above purposes of creating documentation we can identify 3 personas that may want to use documentation:

• future me – when we need to make some modification after a year of work in another project
• fresh developers in the team – when they need to hop into the project and start developing
• users of our project – when we creating a library of API available for other developers

We focus only on technical documentation here but on the last point we can also include business user documentation. On the other side, API documentation is a bit different subject so I will describe it more detailed way later.

What documentation should include?

This is not an easy question. It mostly depends on our audience and purpose. However, we can definitely select some elementary components.

1. Instruction to install or start working
2. Definition of convention in use/contribute
3. How to use project functions
4. How to contribute/extend

I know exactly, that this list don’t exhaust all variety of the most important documentation component, but they are definitely the most common ones.

What are the qualities of good documentation?

I reviewed much documentation. Many of them, I also used in my developer’s experience. Based on this knowledge I can specify some main characteristics of usable documentation.

Searchable

We do this all the time when we want to use documentation. We should be able to search all necessary information as quickly as possible. Generally, we can say that this is the most important functionality for documentation. It can by achieved using regular search functionality

or well-organized table of contents

Provides quick start section

Good designed documentation should be able to help users with different level of knowledge. We should provide a starting easy guide for people who try to use our product for the first time. It is very important to not putting barriers in learning for newcomers.

Documentation should also contain a description of some common parts in the application. For example, it should precise how to handle errors during the use of library and methods to authenticate. All these side notes are very dependent on the context of the project. This is a subject related to typical, common users questions.

Examples

The last, but definitely not the least one characteristic of good documentation are examples. It helps to see how to use some feature in user code. It also enables a way to understand the behavior without writing the function on your own. Especially when we are able to run them straight from the documentation. Examples remove an abstraction layer hidden behind the pure documentation text.

Different approaches to documentation

At the end, I want to share with you, my list of the best documentation which I know

Kendo UI Grid

It contains a good search component and well-organized index. It also has many examples, that we can execute in the browser. Very usable and fast to use.

Aurelia

The same as the previous one has great search and good technical documentation. It enthused me with guides section, that contains a set of general articles depending on your role. You can define that you are a developer or manager and read the guides designed specifically for you.

StackOverflow Documentation

The newest one but the most promising. It is a documentation created by the community, according to the community needs. It has a lot of examples and lives demos in popular subjects. I will definitely follow and contribute to this project in the future.

LESS

The example of quite simple documentation, but very efficient. In fact, in contains all necessary information in the minimalist form. It could only have better search mechanism to tell that it is one of the best.

Knockout.js

Similar to LESS documentation. Very simple and clean. The one distinguish a feature is a form of structuring the subjects. All documentation is written and organized as a story starting from the installation to more advanced functionality.

You can find a good description about creating your own documentation here: https://www.sitepoint.com/products-documentation-good-enough/

Cover photo