What kind of documentation are you writing?

Hopefully the answer isn’t “none”! Let’s assume you’re writing documentation because you’re a wonderful person. Is it a comprehensive discussion of all the features in your software? Good…sort of.

There’s a place for in-depth, comprehensive reference documentation. And that place is often “over there in the corner collecting dust until someone really needs it.” By and large, people are going to need smaller, more task-focused docs. It’s a difference between reference guides and user guides. Or as I like to think of it: “what could I do?” versus “what should I do?” These are not the same documents.

“What could I do?” docs should be chock-full of facts that are easy to discover when you know what you’re looking for. They don’t have opinions, they just list facts. You go to them for an answer to a very specific question that has a correct answer.

“What should I do?” docs should be opinionated. “So you want to do X? The best way to do that is Y, Z.” They’re focused on accomplishing some use case that the reader can probably describe in human language, but might not know how to do technically.

A great example of “What should I do?” docs is the tldr project. Unlike man pages, which are generally reference docs, tldr-pages focus on use cases.

When I was more active in the HTCondor project, I often dreamed (sometimes literally) of writing a book about administering HTCondor pools. The developers had a great reference manual, but it often lacked the more opinionated “here’s what you should do and why.” It’s something we should all consider when we write documentation.

Leave a Reply

Your email address will not be published. Required fields are marked *