Documentation and writer-reader imbalance

With every release of a new API or framework arises the need to specify them in a way that increases their adoption within the community. The quality of their documentation alone can be a differentiating factor that determines whether they will be used or not. This is why it is important to create it with the same level of caution with which we write our code. A documentation should be inviting, because it is the first door at which people knock, when trying to learn something new. If that door remains closed, people are unlikely to come through. Creating technologies is often more exciting than creating the documentation for them. It is somehow considered less challenging and low-value to explain how something should work. Approaching the project deadline is when initial budget constraints can force people to cut down on documentation. This is when they impose a barrier on learners similar to the barrier that has to do with web content accessibility. Only that we speak a lot more often of the latter, which isn't entirely fair. I'm sure that with proper planning, teams can alleviate documentation problems without going over budget.

Depending on the API complexity, documentations can be extremely long, which immediately affects the number of people that will be able to go through them, since they can read only a limited amount of words in a given time. Unless the goal is to make it impossible for them, we should always strive to keep documentation as short as possible. Will we read through it from start to end, before we expect others to do so? If we write only part of the documentation, are we aware of what effort the average reader must put in to understand the material? What does his/her experience look like? How long do we expect to keep the reader's interest, before someone gives up?

It's not enough that the documentation is short; it must be clear too, written in the most effective way possible. This doesn't necessarily mean to be visually appealing if we'll introduce a mixture of bolds, italics, saturated colors, links, tables and diagrams in one big mishmash. We can still use these elements, but do so judiciously, to save the reader from the numerous switches that can be tiring. It's much better to batch things of the same type where possible, then to alternate different styles. Text, text, text, diagram will read much easier than diagram, text, diagram, table, text with individual words in red italic.

We should also try to minimize the things people have to remember while reading through the documentation. If they have to constantly scroll up or down to see how things were, they won't get the maximum of it. In programming, for instance, minimizing the lifetime of a variable is one way to avoid that. To make things easier to remember, it's also better to present a diagram before we explain it and not vice versa, since remembering a visual diagram will be easier than remembering a paragraph of text.

Another issue with documentation is that the number of writers can be disproportionate to the number of readers, creating an imbalance. When many writers feel the need to contribute, the size of the documentation can quickly grow and become overwhelming for a single reader. We can't assume that another team of ambitious readers will be equally excited about the material, so they share their knowledge. A documentation must be written for the smallest unit that can possibly make use of it—the single reader. If we look at long articles online, we'll see that they are often divided in multiple pages for simplicity and digestibility, but this requires additional interaction by the user upon reaching the end of each page. It helps to think about such additional pages as if the article would require so many people to read it in parallel, easily defeating a single reader. A single page shows the amount of content a person can effectively perceive at a time, which is well-known by most online publishers of newspapers and magazines. It might not seem much, but we should not forget that reading on a screen is harder than on paper. With a large documentation, a person would need to constantly readjust his/her frame of perception, resulting in a more fragmented experience.

A large table of contents that has many links even increases this fragmentation, since every link leads to (a part of) a separate fragment. Such documentation can easily become an exercise of clicking around, with people having hard time to retain the connections between things in the way Internet connects them. The table of contents also adds to the documentation, so it doesn't necessarily simplify it. It improves findability of content, but we must question how findable a link is when buried among hundreds of others, since people perceive 7±2 things at a time. A search engine might be a cleaner solution, but then people wouldn't know what to search for. Maybe a combination of both can work? There is no perfect solution for every case and every situation will require a different approach. The only general rule is that people like to read less and "get" more. How this is achieved is something that the writer must figure out.

bit.ly/10XXlp1