What Makes Documentation Bad?

2022-03-05

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