A good technical writer is passionate about their work.
Is passion really enough, though?
I’ve attended technical writers’ meetings that were focused on new forms of documentation, new methodologies, how to push the documentation agenda for a piece of software, how to get people to read the user manuals… there’s a lot of focus on good documentation, which is great! Except… there usually isn’t much focus on useful documentation.
Rarely have I heard someone address the crucial issue:
What do our users need to know, and how can we help them to find the answers quickly and easily?
Why don’t we care about the end user?
Too often, technical writers get stuck in a culture of avoiding the end users. For decades, this was heavily encouraged; when I started out in technical writing, I asked my manager if I could talk to some users of our software. I wanted to know how they were actually using the products, instead of how we thought they should use them. She shook her head sternly. “We’ll give you the use cases,” she said. And soon I accepted that how I would use the software was going to be my only guide to what users wanted and needed.
How can we change?
The trend towards emphasising UX (user experience) in software design is a very important one, and it can teach technical writers a lot. Let’s look at some UX principles that are applicable to documentation:
It’s an interaction, not an upload into the user’s brain
Each topic, each paragraph, each sentence is a conversation with a user. Believe me, they’re talking back – occasionally with swear words attached, but more often by either continuing to read or closing the manual/website/video in disgust.
Users need to interact with your documentation.
Boost the interaction by getting feedback
In these wonderful times in which we live, we don’t have to talk one-on-one with users to get useful information. If documentation is available online, we can use features like:
- Page metrics: bounce rate, length of time that users spend on the page, click paths, and session times can give us insight into whether we’re answering customer questions.
- Search logs: what have website users been searching for?
- Thumbs up/down: we can also use like/dislike, ‘Was this useful? Yes/no’, or star ratings. However we do it, it’s a very direct and easy way for users to give input.
- Comments: most users don’t want to spend time commenting on a help page. If they do, they’re generally either very happy, very helpful, or very very upset. Regardless, we want to know why.
And if documentation isn’t available online, then I have to ask: why the hell not?
Give your users a chance to give you feedback.
Make it easy to access
It’s too easy to forget accessibility. Here are some basic points to think about with every piece of documentation:
- Are diagrams explained for people who can’t see them well?
- Have we made transcripts available for all videos and audio?
- Does the documentation allow for different learning styles?
- Is the documentation all in a single format?
- Can users change the text and background colours?
Make your documentation accessible to as many people as possible.
User needs change over time
The questions that users are asking can change a lot over a few months. This can be for a number of reasons:
- User’s familiarity with the product has improved.
- Product workflows have changed.
- Other products have accustomed users to different processes.
- User needs have changed.
- UI has been modified.
As technical writers, we need to:
- Recognise these changes in the information that users need.
- Produce modified documentation. (*cough* AGILE *cough*)
- Retire outdated documentation.
… and we need to do all of this quickly.
Adjust your documentation to users’ changing requirements as they change.
Keep it simple
While I’ve come across some users who’ll sit down and read every piece of available documentation before touching a piece of software, they’re few and far between. Most users will only access the documentation to find the answer to a question (or because it’s entertaining – don’t faint; it’s possible).
Before writing a topic, ask yourself: What question is this topic answering? One question, one answer, one topic. While it might not work everywhere, it’s a good rule of thumb.
Write each topic to answer a single question that a user might ask.
Every technical writer should be a UX writer too
I say this not to denigrate UX writers or their work, but to point out a truth often forgotten. Documentation is part of the user experience.
When our documentation isn’t useful, we end up with a lot of managers who think, “You know what? We could just get the developers to write our documentation.” And in a sense, they’re right. It doesn’t matter to the end user whether our documentation is a carefully-crafted, beautiful piece of art that angels would sing in wonder to behold, or an incomplete, overly-technical article.
End users care whether a) the doco answers their questions and b) they can find those answers easily. If we’re not addressing those two major concerns, then we’re not doing our jobs properly – and we might as well cobble together our documentation from code comments instead.
Want to read more about UX writing? Here’s a blog post I enjoyed reading: 6 UI Tips That Will Improve Your UX Writing