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:Re: priorities From:Barb Philbrick <caslonsvcs -at- IBM -dot- NET> Date:Mon, 19 May 1997 18:01:58 GMT
I'd add "Accuracy" to the top of the list. I don't care how beautiful
it is, if it's not right, I'll throw it against the wall.
"Filled with Specific Examples" seems suspect to me. It brings to mind
an Rbase database I developed years ago. I used the manual to learn
the program, and it was filled with wonderful examples of accounting
databases. Unfortunately, I was developing a mailing list. I had to
sort through lots of specific examples that didn't help me. I would
have preferred general discussions of concepts with a few general
examples.
"Varied in sentence structure and length" also seems strange to me.
Yes, we want to avoid sing-songy manuals, but we also want to avoid
half-page Hemingway intros with subsequent short choppy sentences. I
think consistency is better than wildly varying line lengths.
Getting back to work now -
Barb
On Fri, 16 May 1997 16:37:44 -0400, you wrote:
>The discussion on typos brought this list of document priorities to mind.
>This applies to technical writing in general, not just typos in resumes.
>
>I'm curious to know the opinions of list readers to this list of document
>priorities. My source is page 11 of "Creating Technical Manuals" by Gerald
>Cohen and Donald H. Cunningham. These are their priorities from highest to
>lowest:
>
>Understandable
>Usable
>Filled with Specific Examples
>Readable (not painful)
>Specific and to the point (not overly general)
>Logically organized
>Well-paced, not dense
>Visually pleasant
>Uncomplicated (in writing and appearance)
>Varied in sentence structure and length
>Correct grammar
>Correct spelling
>Conforms to publication specifications
>
>Cohen and Cunningham also point out that the skill and intellectual effort
>required of publications people is greater for the higher priorities.
>
>
>..............................................................................
>
>Joanne Greene
>Jacobus Technology, Inc. ...developers of JSpace
>URL: http://www.jacobus.com
>
>voice: 301-926-0802 fax: 301-926-2313
>email: joanne -dot- greene -at- jacobus -dot- com
>
>..............................................................................
>
> TECHWR-L (Technical Communication) List Information: To send a message
>to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
> to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
> Search the archives at http://www.documentation.com/ or search and
>browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
>
Barbara Philbrick, Caslon Services Inc.
TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
to LISTSERV -at- LISTSERV -dot- OKSTATE -dot- EDU (e.g. HELP or SIGNOFF TECHWR-L).
Search the archives at http://www.documentation.com/ or search and
browse the archives at http://listserv.okstate.edu/archives/techwr-l.html
