TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:New Year's Documentation Quality Resolutions From:"Snowden, Jim @Cimage" <jims -at- CIMAGE -dot- CO -dot- UK> Date:Tue, 23 Dec 1997 17:13:28 -0000
OK I know Christmas is still to come, but I thought I'd look ahead to
some goals for our documentation in 1998.
My goal is that our documentation would be called "Excellent" by all its
users. I've put down some ideas here of what that might mean and would
be glad for any feedback from other techwhirlers.
In order to achieve that goal, we need to ensure the documentation has
these general characteristics:
Typographically accurate - having good style guidelines, and conforming
to those guidelines.
Grammatically accurate - good spelling and sentence construction.
Complete - covers all aspects of the product (bearing in mind the
Up-to-date - covers the product release the customer is using.
Consistent - uses consistent terms and typographical style.
Maintainable - easy to update the source files with minor and major
product changes, and to publish
Accessible - required information can be found with minimum of time and
Available - required information is always available when the reader
needs to find it.
Understandable - when found, the information can be understood and acted
on by the reader.
Attractive - the information gives a "first impression" reassurance to
the user that it is going to be clear and helpful.
Elegant - the information is presented in a pleasing way that give the
appearance of quality.
Useful - the information is what the reader needs to know.
I could have put in "all our end-user docs will be done in HTML Help" or
"ustomers will be able to download updates from the web". But I'm trying
here to get some qualities of excellent information, and then from those
work out how best to attain those qualities for our range of readers.