DevOps Zone is brought to you in partnership with:

Mark is a graph advocate and field engineer for Neo Technology, the company behind the Neo4j graph database. As a field engineer, Mark helps customers embrace graph data and Neo4j building sophisticated solutions to challenging data problems. When he's not with customers Mark is a developer on Neo4j and writes his experiences of being a graphista on a popular blog at http://markhneedham.com/blog. He tweets at @markhneedham. Mark is a DZone MVB and is not an employee of DZone and has posted 524 posts at DZone. You can read more from them at their website. View Full User Profile

Product Documentation: The Receiver Decides if It's Useful

07.29.2013
| 2413 views |
  • submit to reddit

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.

Published at DZone with permission of Mark Needham, author and DZone MVB. (source)

(Note: Opinions expressed in this article and its replies are the opinions of their respective authors and not those of DZone, Inc.)