Product Documentation: The receiver decides if it's successful
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.
About the author
I'm currently working on short form content at ClickHouse. I publish short 5 minute videos showing how to solve data problems on YouTube @LearnDataWithMark. I previously worked on graph analytics at Neo4j, where I also co-authored the O'Reilly Graph Algorithms Book with Amy Hodler.