Docs are not notes

Digital erosion is equally pernicious

The world is beset on all sides by bad documentation. It’s hard to overstate the scale of the issue. How much human effort is squandered every day stumbling through incomplete, incorrect, incomprehensible documentation? How much is rediscovered, reinvented, and fragmented in the process?

I don’t use the word lightly when I say if there’s anything I hate, it’s bad documentation.

The Forrest for the Trees

Before venturing further, let’s make explicit something we can take for granted. This applies to where documentation should exist. I was lucky enough to have Dave Thomas come and speak at my class. That’s where I learned of The Agile Manifesto (and that I wasn’t alone in my hatred of Scrum). He reminded us:

Working software is the primary measure of progress.

I’m not here to fight on that. I’m not looking for compulsory expelling of docs, comments, design specs, road maps. There are a time and place for them all. But what the have most in common, is that most of the time those are never and nowhere.

The Nine Deadly Sins of Documentation

Uncontrolled

If you let people put whatever lazy, half baked, folklore ridden content in there they want, you’re going to inevitability get all of the above. Ultimately, this is why docs aren’t notes. Docs are considered, concise, and corroborated. You should also have doc builds for those git changes. The rendered webpage? Confirm it still builds. Run a linter to keep the raw format quality high too.

It might seem unnecessarily combative to call off the cuff contributions “lazy”. But that’s what they are. If you can’t bother to take the 3 minutes to submit the change for review, well how much less effort could you have possibly put in? Let’s be honest with ourselves. The desire to do well isn’t enough.

Irrelevant

Don’t waste the reader’s, or the maintainer’s time. Background details, formalities, canned templates? Don’t bother. Should this even be a doc? Clean code is largely self documenting. So are lots of other things. Is it a set of steps? Then ideally it exists as an automation, not a procedure doc.

Stale

If you keep bad information, you train people not to trust and by extension not to use the docs. And then, what’s even the point? If it’s wrong, delete it. If it’s outdated, delete it. If it’s low value or noisy, delete it. (See Unversioned if you’re hesitant)

Redundant

Don’t be this guy: age: u32, // The age. What applies to code docs applies to all. Don’t restate things. Don’t have the same information in multiple places. Worse yet, don’t have the same information in multiple places in different ways.

Duplicative

Don’t re-document a product. Have an internal team whose tool you’re using? Your doc links to theirs. Using an open source tool like cargo? Don’t explain how cargo works. Your doc links to their doc. Duplicating things is simply an opportunity for them to go stale and contradictory. It also harms discoverability.

Proprietary

Docs are naught but words and basic structure. You don’t need, nor want, some fancy piece of software for generating them. This is a distraction, and serves only to harm portability and distribution. The best docs you’ve ever consumed are always in markdown.

Unversioned

Change is needed, and hard to manage. What you have is lots of people, distributed, independently making changes to a large block of primary text. You need to share changes, understand prior context, and be able to rollback. You know who else faces these problems? Software developers writing code. Don’t re-invent the wheel here. Your docs belong in git. Are they related to something that’s already in git? Even better. They belong in the very same repo.

Ugly

Ugly docs beget sad readers. It’s harder to read, harder to care. A beautiful doc works better and encourages upkeep. Your documentation should be rendered into HTML, using a theme that is pleasing and easy to navigate. It should support search too.

Lack of Hosting

Docs that are hard to get at aren’t going to get used. While having things in the same git, in markdown makes them always available, and reusable (e.g. intellisense), we should leverage this accessibility to aim higher. Every cloud has a static web page free tier, as do many git hosts. Configure your CI to build your pretty docs, and publish them to a website. If you work at a big company, consider setting up an aggregated system, or at least having an index doc site that can link to individual product / team sites.

What makes for good docs?

To restate succinctly, in positive form:

• Version controlled with pull requests + doc builds for quality
• Co-located with what is being documented
• Markdown
• Hosted, rendered documentation

That’s really all there is to it. But, seriously, they need to be reviewed. If you only get one takeaway from reading it needs to be this. The others are tried and true examples of what works, especially in the software world, but there’s more than one way to get there. But review isn’t like that. There is no alternative, no shortcut, no substitute.

At the end of the day, you’re battling entropy here. Muck and grime accumulates. Water and wind eat away at structures. And so too do time and the environment confer a digital bit-rot on your documentation. It doesn’t matter how perfectly they start, if you don’t maintain them they will inevitably fall into a state of disrepair.

It’s tempting to think:

But if I make it harder to contribute, isn’t that just making it less likely for documentation to be created?

But that’s specious reasoning. For starters, that’s half the battle. Not letting bad things in prevents most of the problems we’ve discussed. It increases use by increasing usefulness. And when use and usefulness are high, so too is the incentive and reward for investing the effort to properly contribute to them.

We want more information, not more noise. Quality is never what results from unfettered access to anything.

So go forth, and document. Just do it correctly 😉

This blog, like most these days, is all markdown in git with a GitHub Workflow that renders and publishes the content to their static web hosting offer, GitHub Pages.