Over a million developers have joined DZone.

Product Documentation: The Receiver Decides if It's Useful

· DevOps Zone

The DevOps zone is brought to you in partnership with Sonatype Nexus. The Nexus suite helps scale your DevOps delivery with continuous component intelligence integrated into development tools, including Eclipse, IntelliJ, Jenkins, Bamboo, SonarQube and more. Schedule a demo today

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.

The DevOps zone is brought to you in partnership with Sonatype Nexus. Use the Nexus Suite to automate your software supply chain and ensure you're using the highest quality open source components at every step of the development lifecycle. Get Nexus today

Topics:

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

Opinions expressed by DZone contributors are their own.

The best of DZone straight to your inbox.

SEE AN EXAMPLE
Please provide a valid email address.

Thanks for subscribing!

Awesome! Check your inbox to verify your email so you can start receiving the latest in tech news and resources.
Subscribe

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

{{ parent.tldr }}

{{ parent.urlSource.name }}