Create Effective Documentation

Contributed by Charles Humble

Difficulty level: Easy

Over the last decade, as chief editor of InfoQ and then Container Solutions, I helped many engineers improve their blogging skills and realized that many of us suffer from a common affliction—fear of writing. It often starts at school when we perform less well in essay-based subjects and end up avoiding them, believing that we’re no good at writing. But fearing words, and how to use them effectively, is an encumbrance. Writing is a craft, and its principles can be learned.

What is more, words matter. When naming APIs, you know that using clear and unambiguous labels pays dividends since they are difficult to change after your API ships. A poor name—e.g., an API with DeleteFoo and RemoveFoo methods where you’ve wondered what the difference is—lives forever.

While poor API design can put your support teams under strain, bad documentation is like kryptonite. It is the gaps and ambiguities that are the hallmarks of poor documentation, and will ultimately overwhelm both you and your support team. As noted in Google’s “2021 Accelerate State of DevOps Report”, bad documentation kills projects:

“We found that documentation quality predicts teams’ success at implementing technical practices. These practices in turn predict improvements to the system’s technical capabilities, such as observability, continuous testing and deployment automation.”

Good documentation should cover everything someone using ...