What makes documentation bad? I mean documentation as a whole, but I care most about docs within an organization.
Thinking out loud as a reader:
It lacks focus. — Is it a tutorial or a dissertation?
It's clumsy. — I just want simple prose that gets to the point.
It's full of terms I don't understand. — You can tell me "a monad is just a monoid in the category of endofunctors" in thousands of different ways, but I won't understand you until I know what you mean by "monoid" and "category" and "endofunctor."
It's stale. — Often I can't even tell how old it is, or if it still works.
It doesn't break in obvious ways. — When code drifts from what it should do, there's an outage. When documentation drifts from what it should do, nothing obvious happens.
It's ugly. — It doesn't have to be a Cezanne, but I like it to look at least a little bit nice! Usability and an attractive design go a long way.
It's slow. — I'm human and I get impatient.
It's not scannable. — I read documentation for information. The faster I can get the information I need, the faster I can return to my work.
It's hard to search. — Assuming it's meaningfully searchable at all. If I'm in research mode on a new project, the lack is devastating.
It's not owned. — Even the moldiest production service has a nominal owner. But moldy documentation is truly feral.
It's not incentivized. — A culture of writing needs a culture that reads and that respects good writing.
It lacks images. — Not that they're necessary, but they can do a lot of heavy lifting. The right picture is worth a thousand words, and it can be a thousand times easier to understand.
If writing is a tool for thinking, then organizations that don't care about writing don't care about thinking. How do well-intentioned organizations get that way?
Thinking out loud as a writer:
I don't have time. — Or rather, I don't prioritize it given everything else I need to do. Documentation is important, but it's rarely urgent.
I get impatient writing it. — I can type at a comfortable 110 WPM when I put my mind to it, but the speed of type is still way slower than the speed of speech, let alone the speed of thought.
I hate my tools. — I once worked at a company that used Confluence. Every experience I've had with Confluence has been its own day trip to hell. I ended up using Google Docs, as most of our team did, but Google Docs isn't meant to be the backbone of a knowledge base.
I don't know if it's worth the effort. — Writing good documentation feels useful, but documentation doesn't have the obvious and more quantifiable impact that code does.
I have trouble making useful images. — It's only in the last month that I've found a reasonably nice tool for making system diagrams.
I succumb to the curse of knowledge. — The better I know something, the more I take for granted that others understand it as well. What is obvious to me is Martian to someone without my background.
What's the way out? I don't know. But thinking out loud again, here are some ideas that come to mind.
To start, I'd love an English IDE that:
- links technical terms to a glossary
- flags unclear turns of phrase
- highlights basic usage errors
- supports speech-to-text
- looks and feels great when uesd
- focuses on structure and content rather than style and display
- publishes to a clean, readable, and blazingly fast format
- includes tools for making diagrams
The "English as a form of code" metaphor is goofy, but I think we can get something pretty interesting if we push it far enough.
More broadly, I'd love a documentation ecosystem that:
- supports both short notes and multi-page articles
- tracks how many people have read a page and for how long, so that writers and leaders can estimate what impact it has in the organization
- assigns a clear owner and creation date to every page
- integrates a glossary and rich annotations
- flags pages older than X years, Jefferson-style
And even more broadly, all of this depends on an organizational culture that:
- cares about writing as a tool for thinking
- promotes and respects good writing
- invests in good writing tools