Documentation Is More Than Reference

“Great documentation builds trust, differentiates you from your competition, and provides marketing value.” Here, Diana is talking about the good stuff, the stuff that you actually enjoy reading, that you can rely on, and that you might actually extol. (Yes, it exists! Stripe’s docs are a great example).

/via http://geek-and-poke.com/

Unfortunately, in most of our world, documentation is one of those things that is frequently an afterthought. Or worse, left to the #TechBros.

“The code is the documentation”
 — #CowboyDeveloper

Documenting what the code does can be remarkably useful for somebody modifying the code, but is close to useless for somebody that wants to use the system, and doesn’t give a s**t about the underlying code.

The Components
Product documentation should have three clear components

• • Concepts: An introduction to the system, that provides an understanding of its overall purpose , the ideas and concepts embodied in its use, and its main features.
• • Examples: A How-To guide, with examples of usage, including representative samples of parameters and conditions.
• • Reference: Explicit and comprehensive detail on what the system should do, as well as errata on what it actually does.

Which brings us to Reference. The thing to remember about it is that most of it’s value is ex post facto, when you’re trying to figure out why the system is doing whatever it does (“Huh, that’s weird, why do I get back a bool when the default should be int?”). This is the type of information that is meaningless till something goes pear-shaped — which is just about when you wished you’d known about it in the first place!

Necessary vs Sufficient
Reference is necessary, in particular, when you start getting into the nitty-gritty, exploring edge-cases and the like. The “ex post facto” category still holds though, as the reason you’re poring over the docs is usually because you’ve encountered a problem (something doesn’t make sense based on the way you’re using it, you need more details on a specific edge case, or some such).

Unfortunately, Reference is all too frequently considered sufficient, eliminating Concepts and Examples entirely. To the extent that either exists, they are buried within Reference. While this can — sometimes — work for extremely small setups, it rapidly turns into a problem as the APIs grow in number.

The Downside
As cases grow more complex, involving orchestration between various APIs (microservices!), leaving Concepts and Code inside Reference results in either

• • Duplication, as the same “big picture” needs to be explained in multiple places. Keeping track of all the places stuff is replicated is, shall we say, prone to error .
• • Omission, as concepts defined in one place are assumed to be already known in other places. AWS is particularly bad at this (e.g. did you know that accessing ECR images requires that you have access to S3?)

The bottom line — put as much thought into your documentation as you do into your coding. And when it comes to the Concepts and Examples, make sure that you document these separately, and for each idea at that. If there are too many use-cases (e.g., your tooling is like lego blocks), don’t worry — pull together representative examples to provide sufficient coverage (you’ll probably get it wrong at first pass, but hey, you can always add more!).

“Documentation sounds like Communism”
 — #CowboyDeveloper

Above all, don’t succumb to the know-it-all insanity of #TechBro culture! The last thing you want to go for is an elitist culture — one where only the High Priests understand how the system works. It’s limiting, it’s arrogant, and it’s also just plain dumb.