Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Product Documentation: The Receiver Decides if It's Useful

DZone's Guide to

Product Documentation: The Receiver Decides if It's Useful

· DevOps Zone
Free Resource

Download the blueprint that can take a company of any maturity level all the way up to enterprise-scale continuous delivery using a combination of Automic Release Automation, Automic’s 20+ years of business automation experience, and the proven tools and practices the company is already leveraging.

One of the things I remember being taught while growing up is that in an interaction where somebody is something to someone else it’s their responsibility to do so in a way that the receiver can understand.

Even if you think you’ve done a good job of explaining something, the receiver of the communication decides whether or not that’s the case.

I’d always assumed that this advice made most sense in the context of a one to one conversation but recently I’ve realised that it also makes sense when thinking about product documentation.

Most products on the market have some sort of documentation available which is a good first step but I’ve still seen a couple of ways that users of the product struggle:

It’s too complicated

Frequently documentation is written by an expert of the product so the language they use is very technical and difficult for a novice to understand.

It’s often worth running documentation past a non expert to get a sanity check but a tell tale sign that documentation may be too complicated is when you get a lot of questions about things that you believe it covers.

At this point we can often work out what has led to user confusion and then make the appropriate changes.

People can’t find it

Sometimes there’s no problem with the documentation but people can’t find it.

This might be because it’s poorly titled or doesn’t use the same language that users use when they are trying to solve a particular problem.

There’s a tendency to believe that users should learn the language of the domain and while that’s true to an extent, if we can work out what language they use it can reduce friction and lead to a better experience.

The other problem users encounter is where they find the documentation index but are then overwhelmed with information to the point where they’re not sure what they should be clicking on.

This can be solved by focusing documentation on the simple case but having links through to more advanced topics for people who are interested.

Further reading

Tom Preston Werner wrote a post a few years ago around this topic titled ‘Readme Driven Development‘ which is worth a read.

Joe Walnes uses a similar approach on his projects – Smoothie Charts and WebConnect are a couple of examples that I’ve come across.

Download the ‘Practical Blueprint to Continuous Delivery’ to learn how Automic Release Automation can help you begin or continue your company’s digital transformation.

Topics:

Published at DZone with permission of Mark Needham, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}