March 04, 2012
|
Golden Rules of Technical Writing
|
2255 hit(s)
I've been working on some thots about what we do and how and why. I'm trying to come up with some Golden Rules for technical writing. Here are 12 to get started.
Planning
- Produce the information that your customers need. Forget everything else.
- To learn what customers need, talk to them.
- Take advantage of what's already available in your community, and work only on something where you add value.
- Know your audience. Understand what they know (and don't) and how they work.
- Know your product. Understand what it's for and explain to users how it solves their problem(s).
- Consider that the best "documentation" might not be documentation. It might be good product design instead.
- Don't assume producing documentation means writing. It might mean producing video, audio, or some interactive something-or-other.
- Prioritize. You can't produce everything, so produce the content that has the highest impact.
Writing
- Remember that people turn to documentation only as their last choice, and write accordingly.
- Focus on 3 C's (in order): correct, clear, concise.
- Know what you need to say, and say only that.
- Get yourself reviewed/edited.
Agree? Disagree? Items to add? Remove?
|
|
