Re: Developer wants to take over documentation

["Ivie, Guy" <GuyI -at- CORPMAIL -dot- FOLLETT -dot- COM>]

A couple of years ago, I had to talk to a group of engineers of various
stripes about improving their writing skills and using MS Word. They were
"publishing" their notes in a networked database that gave everyone,
engineer and non-engineer, on the project(s) access to stored Word files.
In an afternoon, I talked about writing simple, declarative sentences (as
opposed to engineer-ese and/or manager-ese), cutting out excess verbage,
why active voice is better than passive, and why imperative works best
for instructions. I also talked about using style sheets and templates in
Word to standardize the appearance of the documents. The following week,
they asked to me teach a couple of clerks how to set up and maintain the
styles and templates. I heard later that everyone was content with the
documents that were put up on the net.

Keep in mind that (to the best of my knowledge) these documents were
engineering notes, not formal documentation. You may need to cover format
issues in some detail, as well as content (don't forget to include...),
if the developers are going to produce manuals.

Hope this helps.

Guy Ivie
Follett Campus Resources
GuyI -at- corpmail -dot- follett -dot- com


 ----------
From:  TECHWR-L[SMTP:TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU]
Sent:  Tuesday, April 29, 1997 14:02
To:  TECHWR-L
Subject:  Developer wants to take over documentation

Have any of you ever encountered a developer who wanted to take over the
documentation?  It's just happened to me for the first time in my 11
years as a TW.  And when he brought it up, a few others said they would
like to, too.  Basically, it looks like I might have to teach developers
the idiosyncrasies of publishing, with Word no less!!!!!  Any advice
will be greatly appreciated.  I have to make a presentation Friday.


Thanks,

John Wilcox, Documentation Specialist
Timberlands Information Services
Weyerhaeuser, WWC 2E2
Tacoma, WA  98477-0001
206-924-7972   wilcoxj -at- wdni -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

 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