Tuesday, March 14, 2006
Principles for technical writers
While doing some research the other day, I stumbled across document titled Ten Principles: A Technical Writer's Primer. Aimed at those new to technical writing, this little eBook offers 10 solid pieces of advice on technical writing and dealing with subject matter experts.
The following three principles are especially trenchant:
I’ve seen too much documentation deviate from those principles, much to the detriment of users and the quality of the documentation alike.
The following three principles are especially trenchant:
- Principle 3: Never Use a Programmer's Words to Explain How Something Works - Always Use English.
- Principle 6: Verify, Verify, Verify - Skepticism Is a Way of Life.
- Principle 10: Always Expect Your Readers To Get Lost. Do Everything You Can To Keep Them On Track.
I’ve seen too much documentation deviate from those principles, much to the detriment of users and the quality of the documentation alike.
