"How Tech Writing Sucks: The Five Sins
," from interface designer Amy Hoy, addresses five ways in which we, as a community, fail to communicate. Addressing the ability to write is important, since the internet is ultimately about communication between people.
If you can't communicate effectively, nobody will care about your message, no matter how worthwhile it is. One wishes that Sun would get that in their heads once in a while.
The five sins, Ms. Hoy says, are:
- Losing the reader
- Making the reader feel stupid
- Failing to stick
- Being a total bore
- Not providing much-needed context.
Most of these are obvious, but they all fail from a misunderstanding of what technical writing is supposed to do: inform and instruct (in varying qualities.) She even offers a three-step attack plan to fix it:
- Describe the symptoms
- Identify the underlying causes (admitting you have a problem...)
- Attack! (a prescription for betterment)
Now, your Humble Editor can only hope he doesn't hit too many of those sins... (have I lost you yet?)