When you ‘man awk’ you will be presented with a superb piece of technical writing. The awk manual is succinct, precise, clear, and unambiguous.
But what if you are new to Unix? Alas, for noobs, the awk manual is gibberish. If you aren’t already familiar with the Unix pipe operator (|) and output redirection operator (>) awk’s value proposition is lost.
In other words, it’s the context that you bring to a subject that determines how much value you get out of the documentation.
Forcibly taken out of context
Awk was written in 1977, eight years before the first release of Windows. In that computing environment, the creators of awk could safely assume that anyone reading their docs was a fellow Unix programmer. Given the overall size of the computing ecosystem in 1977, who else could it be?
But a lot has happened since 1977.
The new hotness is to herd people into specialized functional roles, like SRE, or Front End Developer. When this happens you gain operational efficiencies, but you lose global technical context.
Another apparently irreversible trend is to organize around autonomous product teams, each optimized to iterate on a single value stream. When this happens you gain market sensitivity, but you lose global business context.
We have also dis-integrated software itself, to the point where we have singular operations executing in isolated and ephemeral runtimes, all hanging together in a compute environment that is hyper-efficient, but fundamentally opaque. When this happens your platform no longer has a bordered surface and it has essentially bled into the matrix.
Given the breadth and complexity of the modern tech ecosystem, how is today’s programmer supposed to write documentation? Who is the audience exactly? Is it the
- Product manager
- Sales engineer
- Front end developer
- Back end developer
- Mobile developer
- Devops engineer
- Software architect
- Data scientist
- User experience designer
You get my drift. By systematically converting generalists into specialists, we have organized tech in a way that reduces our ability to provide global context, while simultaneously making the need for global context painfully acute.
Value or virtue
What could be dumber than to ask developers to provide context they don’t actually possess, for an audience they know nothing about?
Under these circumstances, if you ask programmers to produce documentation, they will oblige, in order to preserve status. But to preserve sanity, they will automate the process so that the requirement can be satisfied with minimum effort.
This is why much of the documentation produced today reads like it was produced automatically, in a manner meant to reduce toil rather than maximize value.
From a developer experience perspective this all smells very bad. If you are the person who has to produce documentation, the task feels like a worthless ritual, because TAGRI. If you are the person who reads documentation, instead of the context you crave, you receive an anodyne recitation of parameters and data types. What are you supposed to do with that?
Documentation that delights
The thing is, it’s actually pretty easy to delight developers. First, provide context by explaining what types of problems your platform can solve. Then prop up your boring OAS specs with how-to articles and sample code.
Companies that can do those things consistently become the de-facto subject matter expert in their problem space.
For example, if you want to learn about real-world payment implementations, start with Stripe’s documentation.
If you want to learn about real-world SMS implementations, start with Twilio’s documentation.
If you want to learn about real-world e-comm implementations, start with Shopify’s documentation.
And so on.
The not-so-long game
Just for fun, imagine what would happen if your company were perceived as the de-facto thought leaders in your problem space.
What kind of employees would you attract?
What kind of opportunities would present?
What kind of doors would open?
As Twilio can attest, documentation isn’t a distraction from the game. It is the game.
Next week’s article will explain the secret to delightful documentation and how it fits into the modern socio-technical space. I call it How-To Driven Development (HTDD).
I'm hiring software engineers! Check out the jobs page to see my open positions.