What’s the point of tech docs anyway?
As a freelance technical writer, this question – and variations upon it – is one I’m asked with dependable regularity. Each time it comes up, I’m reminded of two phrases that I heard a lot during my first year as a technical writer:
“Just document around it.”
“Nobody reads the documentation.”
You might think the second was said in response to the former. It wasn’t. More often than not, both statements would be made by the same person over the course of a single meeting. Look past the apparent contradiction and the underlying sentiment is clear: technical documentation is an exercise in protecting the team or business from criticism (also known as CYA).
As someone new to the industry and hoping to make a career as a technical writer, I’ll admit I felt a little demoralized after the tenth repetition.* But I’m also stubborn, so I refused to accept this view without questioning it. Can technical documentation offer more than just a tick in a box? If so, what form does that take?
Just document around it
Part of my motivation for entering the field of technical communications (“tech comms”) came from my own frustration with using software as a child in the nineties. Very often it felt like programs were unnecessarily complex, with confusing terminology, circuitous workflows and inconsistent designs. I wanted both to understand how everything worked and make it easier for others to do the same.
This attitude of “just document around it” reminded me of the kind of documentation I’d been exposed to with the first home computers: weighty printed tomes and vast CHM files describing each setting, configuration option and command. Everything was covered in painstaking detail, but it didn’t actually tell me how to achieve what I wanted.
Fortunately, the industry evolved in the intervening years and principles of human-centred design and usability began to influence software design. The teams I worked with in my first tech comms role had bought into these ideas; they took the time to understand the users’ needs and tried to design workflows and interfaces with those in mind.
For them, “just document around it” was a judgment call. With limited resources, you can’t always address an issue properly by designing a more elegant, intuitive solution for our users. In that case, the fallback was the documentation.
But, if no one reads the documentation, where is the value? We’re still reducing docs to an exercise in CYA.
Nobody reads the documentation
It’s true that most users don’t read technical documentation for fun. There can even be some reluctance to consult the documentation when stuck. However, in the business-to-business context (which is the realm I work in) documentation is almost always expected and it does get used. You can see this from page views and references to specific articles in support tickets, and it’s inevitable for products with license agreements that offer a limited number of support hours.
So, the issue is not that people don’t read the documentation, but that they don’t want to. As a writer wanting to add value, the question becomes, “How do you make the experience as painless as possible?”
Rethinking tech docs
For me, the first and most important point is that not everything needs to be documented. In particular, there’s no value in writing a manual that describes each screen in the UI.
Users don’t need to be told how to use a drop-down menu or radio button, and they shouldn’t need an explanation for every single check box. (There may be exceptions for users that are not IT literate, but that rarely applies in a B2B context.)
If you think this level of explanation is needed, it’s time to review the UI design: do the labels, groupings, and order of elements make sense? Would a tooltip or string of explanatory text help? Where possible, giving assistance at the point of need is far less disruptive to the workflow than linking out to an online help system or leaving your users to find their way there alone.
Second, the content that you do write needs to be focussed on what the user is trying to achieve. To do that, you need to understand what problems your users are facing and why they matter.
In showing users how to solve that problem, your user guide might guide them through the UI but it doesn’t require an exhaustive explanation of each mouse click. Rather, it should address anything that isn’t obvious, such as complex settings and subtle differences, offer advice on best practice and direct the reader to related topics.
By taking this approach, you end up with a smaller, more focussed set of documentation that addresses specific user needs, thereby helping your users to get the most out of your product.
Enabling the value-add
If your tech docs are currently just there to tick a box on a list of requirements, how can you turn them into a valuable part of your product offering? In my view, one of the most effective moves is to recognise that tech comms is part of the software development process. Allow your technical writers to work alongside product managers, usability specialists, designers, developers and testers. It’s the most efficient way to ensure writers build an understanding of both your users and the product, while allowing them to feed into the development process and reduce the need for documentation. After all, no one wants to read that stuff, right?
* At some point I even suggested we get t-shirts with these statements printed front and back. Fortunately, the other authors refused.
