Effective Documentation

Let's be honest. Nobody reads documentation. Developers are too busy writing code, shipping features, fixing bugs - in other words, getting real work done. Nobody likes writing documentation either, yet developers are encouraged to create and maintain high-quality docs. Both problems can be addressed with effective documentation.

Why I write documentation

Eventually, every developer gets stuck. I'm not sure which function to use or why my API call doesn't work. I could ask around or dig through source code, but what would help me most is effective documentation. Hunting for answers elsewhere can be slow and unreliable. When written effectively, documentation provides precisely the answers needed from a trusted source.

There are countless solutions to any given problem in software engineering. Within organizations and teams, it becomes important to select a consistent solution for maintainability. Without documentation, every individual might choose a different implementation. So, effective documentation not only unblocks developers, it provides consistent answers to recurring questions. If documentation is so powerful, why doesn't anyone read it?

Why I don't read documentation

If I search for "Golang read request body" I find a myriad of opinionated answers from blogs and Q&A aggregators. The answers vary in quality and age. The official documentation has an example of reading the request body right at the top, but barely makes it to the first page of results.

Unfortunately, the right documentation is hard to find. This is especially true for internal documentation that doesn't benefit from public search engines. And when I do find the right documentation, it might not directly answer my question.

Many public documentation sites are huge blobs of interfaces and functions. I have to assemble my own answers from the information provided. On one hand, this makes the documentation flexible. On the other, I need enough context and background information to form these answers myself. Sometimes this takes longer than is worthwhile.

To be effective, documentation has to unblock developers quickly. Long walls of text take time away from my work, and I'm not guaranteed to find the answers I'm looking for. Worse, if I need the answer again in the future, I have to re-read. What I want instead is to quickly reference documentation when necessary.

Nobody reads documentation, they reference it. So, documentation should be written not to be readable, but to be referenceable.

Writing referenceable documentation

Referenceable documentation is answer-oriented. Developers come to documentation with questions. The documentation should answer them. A Q&A format isn't necessary, though. Like in the Go HTTP package documentation above, a simple code sample can tie together a list of functions. The important part is that the reader's questions are answered first and foremost.

Referenceable documentation is focused. I shouldn't have to dig through the project's history and technical implementation to clarify a function's operation. That information is useful, but shouldn't slow down a developer with a simple question. Put it in an explanation or tutorial instead. In the same way monolithic services are broken up to separate concerns, documentation should be separated into referenceable pieces. This allows readers to read just as much as they need and want.

Referenceable documentation is illustrative. A picture is worth a thousand words. A code snippet, maybe twice that. These illustrations are memorable, shareable, and of course, referenceable. When combined with focused, answer-oriented text, illustrations and examples can unblock a developer faster than any other format.

Examples from the wild

It's Sunday morning. I'm hungry, so I head to the kitchen to make a soufflé omelet. I pull up the documentation (recipe) and get started.

Well that's not helpful. I'm sure my answer is down below, but now I have to go looking for it. Although this information is interesting, it's not focused on my immediate needs. As for illustrative, I'll admit there are some tasty looking photos further down.

It's Monday afternoon. I have to combine two JavaScript arrays but forget if concat() modifies the array like push() or returns a new one. I head to the documentation in search of an answer.

My question is answered in the very first block of text, supported by a live code snippet. The lesser-needed details are separated into other sections. In seconds, I'm unblocked and can get back to work.

Although simple, these examples showcase the principles of effective documentation. I'll cover more complex examples in a future article: Effective Documentation by Example.

The writer's time matters too

I avoid saying good or excellent documentation because those terms imply high quality writing, formatting, and design. Beautiful prose and literary devices are not necessary for effective documentation. I write with clear language and short words. And the presentation can be simple - there's no need for animations and transitions. Writing documentation shouldn't be a monumental effort.

The writer's time is just as important as the reader's. After all, they are also a developer that could be getting real work done. Writing documentation is an iterative process. Start with answering the most common or important questions and add more over time. A simple diagram or code snippet might answer a majority of questions readers have.

Effective communities

Anyone can write documentation. Everyone should write documentation - it's too invaluable not to. It doesn't have to be for a system you created, or even one you're an expert in. If you can answer a question, you can write documentation.

Internal documentation is often kept in wikis or other collaborative writing tools. If you find inaccurate or ineffective documentation, change it. You may not be the original author, and maybe it's not your service, but it's your documentation. Effective documentation is a community effort. Just a few moments of your time will make everyone around you a little more... effective.