Have you committed a technical writing sin?
I’ve been re-reading some old posts in the field, and after reading Amy Hoy's Slash7 post on "How Tech Writing Sucks: The Five Sins," I started thinking… is it really possible not to commit any one of the five sins?
The Five Sins -
- Losing the reader
- Making the reader feel stupid
- Failing to stick
- Being a total bore
- Not providing much-needed context
Hoy says the five sins are results of "bad" writing, but can you realistically prevent these things from happening for all users? As a n00bie in the field, I’m learning how to ensure the reader is getting what she needs out of the documentation. One objective of documentation is… user needs help, refer user to a guide or help file, user resolves issue on her own, and in doing so, saves user time and a phone call to customer support. Pretty simple... the objective at least seems that way, but now comes the tricky part.
How do you keep the reader engaged with relevant, lively content, without feeling stupid, so she can remember it the next time she completes the process?
Seems straight forward, but then again, we are discussing user guides and help files. These materials aren’t usually opened unless there is an issue, and then they are closed as soon as the issue is resolved. I guess what I am proposing is, these sins are sometimes inevitable. Here’s why…
- You will lose the reader as soon as the issue is resolved.
- No matter how you write, you’re going to make some reader feel stupid – either talking above or below them.
- Most of the time, the content users are looking for is not everyday occurrences. Failing to stick is predictable and they will have to search for the answer again.
- No matter how pretty you make it look, technical documentation is not going to be the most exciting type of reading available. How many manuals have ended up on the bestseller’s list?
- Can you document everything? Probably not. So anytime a user cannot find something she is looking for, she is going to find it lacking.
I understand we are supposed to write in a way that best prevents this from happening, but perhaps it’s just the nature of the beast. You can’t expect to satisfy everyone can you? But I bet you can expect to commit one of these "sins.” What do you think? Can we strive for and achieve sin-free technical content? And if not, is it good enough to learn from our mistakes and keep improving as we go along?