Skip to main content

Write better docs

· 3 min read
zach wick

That sentence might be a vague instruction coming down the chain-of-command to you. That sentence might something that you aspire to do. In either case, that statement of "Write better docs." might be something that you’re actively working to do. If you find yourself in this final group, then this text is for you.

You already know that the documentation that you create should be useful, but what does that mean in practice? Does it mean that users can use your documentation to solve their implementation issues? Does documentation being useful mean that your documentation helps users improve their business processes? Or does useful documentation only mean that its existence is a positive value proposition by your sales counterparts?

Useful documentation can do all of these things and more.

Documentation is the force multiplier for marketing efforts when the product being marketed is a shovel or pick in a gold rush. Good documentation can make a poorly marketed product sell decently and great documentation can augment great marketing to best-in-class.

For businesses making software building blocks and selling them as these picks and shovels in the Big Tech/Silicon Valley software-as-the-savior gold rush, best-in-class useful documentation rewards as both an economic return and as an increase in the quality of the portion of the customer base that requires support.

Making useful documentation isn’t just getting rid of passive voice and putting in lots of screenshots. Making useful documentation requires a full reframing of documentation as a product experience where the reader is taken on a journey through the implementation and nuances of how your product applies to their scenario.

Documentation is usually treated as a hastily thrown together, constantly out-of-date content-island. Treating documentation as an educational experience instead allows for the documentation experience to instill lasting impressions in its participants. For readers of useful documentation, their personal educational motivations are aligned with their immediate business needs and the spirit of the documentation. By teaching these participants how to apply your product as the best possible solution to their particular business problem, your product's positive associations with that user are increased and you have a perfect opportunity to educate them on the why of your product's features. These active learners form an audience of highly motivated learners and are a captive audience for marketing messages.

A user who understands why and how your product functions is educated on your product with declarative knowledge of what your product is and procedural knowledge of how to use your product's features. Such knowledge transfer is the purpose of the field of study of Instructional Design.

This means that if documentation experiences are treated as educational experiences, then they can be made more impactful by analyzing them through the toolset and frameworks of the instructional design world.