Next to API docs, UI/UX is one of the fastest growing sub-domains in technical writing. Not surprising, because documentation contributes to the user experience and explain how to use a product's user interface.
In May, I spotted an article by Robert Hoekman, Jr. that I've now read several times. He called it a "UX Reality Check" for designers. It's easy to get distracted by your product and forget to look at the world through your user's eyes.
As I read through, several points stood out as being just as applicable to technical documentation. Here are the bullet points from the article that stood out to me the most.
- Users don't care about learning your system
- Users do not want to spend all their time on your website
- Users are always in "doing mode"
- Users only want to know enough to "get by"
- Users will use your product in ways you cannot anticipate
- Users look for patterns they are familiar with. Violate them at your own risk.
- Your docs are not their priority.
- "Users see what’s actually there. Not what you think is there."
- Users will give you recommendations and feedback, but you need to read between the lines and understand the underlying reason they're making them and address that.
- What's self-evident to you is a mystery to them.
- Anticipate user questions and provide those answers
- Everything affects the user's experience (not just your docs)
The lessons from this list underscore the reason the trend in technical writing has been towards topic-based writing. A technical documentation professional could have easily written this same list!
For years, everyone has been telling technical writers to, "Focus on the tasks." Focus on what the writer needs to do! Don't describe the theory. Create clean reference pages that they can refer to quickly to get what they need. Don't bury the important stuff in layers of unnecessary, low-value content.
Isn't this all echoing the same points listed above?
- Focus on the tasks ("the user is in doing mode)
- Users only want to know enough to get by (focus on what they need to do)
- Users don't care about learning your system (Don't bury important stuff in layers of conceptual material.)
That's why I saved the article and have read it more than once. It could just as easily have been written by a technical writer talking about how to write great documentation.
The original article listed 14 points (not 12). I didn't include them here because they are more suited to the UX designer's world than techdocs (for example, techcomm folks rarely get to do usability tests or user interviews). If you're interested, here's the whole article. It's a fast, thorough, and fun read.
Get useful tips and valuable resources every month
Join the thousands who know just how much we share.