RE: Technical writing in a higher ed environment

["Wendy Cunningham" <wcunning -at- pct -dot- edu>]

"Much of my content (quick guides, cheat sheets, basic 'how to'
information, etc.)  is distributed electronically via the Web site and
is subject to this "law." But AP doesn't even come close to meeting my
needs. In fact, it often contradicts Chicago and other style guides
commonly used in technical documents.  What's a writer to do?"

Thanks to all who responded to my call for advice. Although many of you
disagreed on certain points and some felt the issue was trivial, I
gained some valuable perspective.  Some comments that really struck
home:

Gene - Style guides are supposed to be defined to suit the intended
purpose of the document, not the other way around.
Dick - You have experience and specialized needs on your side.
Lisa - I wouldn't worry about it unless someone is looking over your
shoulder. If someone does ask, you can calmly explain why you have
additional needs. 

So... I will do what I feel is necessary to present my technical
information with clarity and conciseness. When AP conflicts with this
goal, I'll use Chicago or other appropriate source as my guide.
Ultimately, the person who established AP as the sole style guide has
never written technical documentation and has never worked with a
technical writer. I will keep a record of AP 'deficiencies' (thanks
Bill) as CYA in case I'm ever confronted. 

For those who did not understand why I feel AP is inadequate, I'd like
to thank Gene for his on-target response: "If you imagine an instruction
manual written like a USA Today front page article, that will probably
answer your question." My audience, of course, is familiar with the
style found in newspaper articles. This hardly means that it's the
appropriate style for instructions telling them how to set up e-mail
filters or how to install a virus protection application.  

Here's one example of how AP falls short. At one time or another we
have all had to consider the "rules" for when to use figures and when to
write out numbers. AP style says: "Spell out whole numbers below 10, use
figures for 10 and above." Seems simple enough. Until you need to use
multiple numbers (all of the same category or context) in one sentence.
AP gives the following example of appropriate use: "They had 10 dogs,
six cats and 97 hamsters." Doesn't that make the you cringe?

Technical writers are trained to honor consistency above all else.
Chicago says not to use numerals for some and spell out others within a
sentence or even a series of paragraphs. For consistency's sake, it
directs us to use numerals for all in this situation.  

Sorry to ramble. 

Thanks again,
Wendy

Staff Development Specialist/Technical Writer

 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ROBOHELP X5 - ALL NEW VERSION. Now with Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! 

Now is the best time to buy - special end of month promos, including:
$100 mail-in rebate; Free online orientation on content management
functionality; Huge savings on support and future product releases;
PLUS Great discounts on RoboHelp training. OFFER EXPIRES March 31! 
Call 1-800-358-9370 or visit: http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.