The best docs are the ones we don’t remember
I’m a terrible user of documentation. I tend to consume docs in a hurry, reading diagonally, Control+Fing my way to things. I generally mistreat the interface of docs until I obtain something resembling an answer. I do this because I’ve little time and I need to fix issues fast. I love examples I can copy and paste. I’ve little patience for verbose documentation and even less for docs that look like they were written without care or skill. I’m not only bothered by inaccuracy, but also by bad style. In a way, as a user of documentation, I’m the worst nightmare of a technical writer.
Most of the documentation I use happens to belong to open source software. Open source projects need great documentation, but contributing to it takes time and energy. As a docs engineer, most of the documentation I read every week is made of half-baked README files that were cobbled together at night time, fueled by energy drinks and hubris. Some are so devoid of information that I end up reading the source code and the issues. When I’m lucky, I get to read some decent docs in ReadTheDocs or Github Pages that feel smart because they follow Diataxis or use MkDocs.
So when someone asks me what my favourite docs are, I’m never quite sure what to answer. My first impulse is to mention printed manuals from the 80s and 90s, when documentation was authored with care by folks who crafted printed products called books. This isn’t snobbish: Docs were better back then, and online docs are getting near that level only now, because folks are realizing that docs are infrastructure and that lacking docs is the worst offence a software product can commit.
That doesn’t mean that I don’t have docs I like. In fact, there are docs I admire, but only because I spent too much time reading them.
The best docs are the ones we don’t remember
Asking me what’s my favourite documentation is a bit like asking me what are the best doorways I’ve crossed in my life. We remember places, not open doors; we recall the things we did through software, not great docs. In my case, I seldom remember good or great documentation because its purpose is not to get in the way. On the other hand, I do remember lots of bad documentation when it failed to provide answers. The curse of technical writing is that the best expressions of our work are the ones people rarely notice, because they offer so little friction they never disturb the user’s flow.
There are exceptions to this, of course. The first is documentation that is presented in such a way that it generates a “Wow” moment. Perhaps it’s a code snippet you can run, an interactive demo, or similar gimmicks. While they’re not key to great documentation, they make for some memorable experiences, though that can backfire quickly if the docs aren’t good. The other exception are docs that teach us something new, either through conceptual explanations or examples. Some of the best docs I’ve read are aware that they’re also teaching new ideas and concepts. You can tell because they grin.
The docs I love to rediscover
The following list contains some of the best online documentation I’ve come across. It’s not meant to be an exhaustive list, and I’m pretty sure I’m forgetting documentation that was so good that I didn’t even need to re-read it. Or perhaps it impressed me because of its clever design, or for the knowledge that transpired through its carefully written paragraphs. Whatever the reason, this is the documentation that I most frequently remember.
Rust
When I said that docs grin when they’re aware that they’re opening new avenues in people’s brains, I was thinking of the Rust documentation. It’s not only expertly done and complete: it’s also written in a delightfully confident style, the same you’ll find in foundational manuals like K&R. Of course, Rust docs are also a book, which perhaps explains why I like them so much. They have flair, personality, and also a bit of humor, all things that help make a documentation experience memorable.
Splunk
I worked at Splunk for three years and a half, so you’d say I’m biased, but their documentation is still one of the best I’ve ever used. What stands out it’s its completeness and how well it’s written, thanks in part to the excellent Splunk Style Guide and the tireless effort of the Splunk editors. All the good practices in Microsoft’s, IBM’s, or RedHat’s docs you’ll find perfected in Splunk’s. They’re still a paragon of quality in a landscape of ephemeral docs. Commitment matters.
Viam
I got to know Viam’s documentation when I was a juror of the Dev Portal Awards. I immediately loved the design of their docs and their approach to graphic design. You can tell from the very beginning how much love and care they’ve put into each visual element, as if they were editing an award-winning book. (You see the pattern behind my choices now? Yes, it’s books.) The key to Viam’s success as a docs portal is the pure joy they convey about what they do. What’s not to like about joyful docs? What’s not to like about docs made with love?
DigitalOcean
The last mention goes to DigitalOcean, and the reason is, again, coverage and generosity. Who hasn’t come across DO docs when trying to set up a web server or configure .htaccess files? As a web hosting company it’s not their obligation to document third-party solutions, and yet they understood that someone had to explain how to drive the car in addition to selling it, which I think explains their success. Docs in the same category are MDN and even W3Schools. Generosity matters.
How can one create great documentation?
Looking back, I think I’ve never created great documentation. But I’ve contributed quality docs to great documentation projects and supported processes that allowed docs to happen at all, which is what makes technical writers sleep well at night. If that sounds slightly depressing, it’s because it is: Being a technical writer for software these days is like trying to bootstrap an entire publishing industry in some caricature of the Middle Ages, like the one in Army of Darkness—inventors busy at prototyping intricate trebuchets and wondering what the lone writer is yappering about.
And yet, the examples I’ve shared show that great docs can happen when there’s a strong editorial vision and the resources to bring it to life, when docs aren’t an afterthought. One doesn’t simply create great documentation. But with enough care, collaboration, and a little love, we can get close. And maybe, that’s more than enough.