There was a post submitted to the Orange Website™ the other week with the title “Delete half your documentation” (HN thread here).
The author talks about how documentation inherently has a cost, and how we should minimize the amount of documentation we need. It becomes outdated, requires maintenance, and “nobody reads it anyway”.
Instead, they argue, we should use type annotations, tested examples, and other methods to remove the requirement for manually maintaining documentation.
Some of these arguments have some merits in the right context.
But what really caught my eye in the post was this line:
“When I say 'documentation', I mean all forms of it, including README, Markdown files, docstrings, and code comments.“
Hang on.
This is not all forms of documentation! And we certainly cannot apply these rules universally.
Documentation is in the eyes of the reader
I recently Tweeted about the confusion that can happen when people use the word “documentation” to refer to different things.
The word ”documentation” has so many meanings depending on who you’re talking to.
— Niklas Begley (@NiklasBegley) September 6, 2023
To one person it’s a single README file. To another, it’s a full blown dev portal with guides and API references.
Causes legitimate confusion sometimes
The post mentioned above is a great example of this phenomenon.
The author clearly had the view that “documentation” means code documentation: docstrings, and other supplementing information you can include in or generate from raw source code.
This is quite natural for software developers, since it’s the kind of documentation they are used to producing themselves. And for their case, perhaps relying on automation over prose to ensure your documentation is in order is a good idea.
But what about developer portals, manuals, or API references? Surely a technical writer documenting a complex developer toolchain should not apply the same thinking and “delete half their documentation”?
An overloaded term
Technical documentation comes in many forms. Developer portals, docstrings, walkthroughs, internal knowledge bases, marketing documentation, SDK documentation, various kinds of manuals.
It’s hard to apply universal rules as best practices for all of these categories.
The amount of effort you are willing to invest into your public developer documentation compared to a small internal library is wildly different. The former can have professional dedicated writing staff constantly improving the content, while the latter may be written once and rarely updated after.
The context will determine what best practices, tools, workflows, and expectations are valid for any given type of “documentation”.
Documentation is more than docstrings and READMEs
When we talk about documentation, we shouldn’t limit ourselves to README.md files on GitHub. It’s a much richer field.
There’s a whole world of professional technical writers that have advanced tooling and workflows for producing documentation for some of the most beloved developer tools out there. Documentation can make or break companies trying to reach a developer audience.
You probably should not delete half your documentation.
Articles about documentation, technical writing, and Doctave into your inbox every month.