RE: format-monkeys

["Rock, Megan" <Megan -dot- Rock -at- fanucrobotics -dot- com>]

Hideous, perhaps, to some people, but for others, that's the best way to
handle minor changes.  Our SMEs much prefer to mark up the existing
documentation when changes are relatively minor.  Often the changes are so
small and buried within the software that we technical writers would never
find it no matter how much we played with it.  

For example, we have tens of thousands of system variables that our users
can set to customize the installation and operation of the robot controller
software.  We also have thousands of error codes that might pop up on the
user's screen during setup or production.  The developers know when they add
or modify a system variable or error code in their source code, and it's
much more efficient if they just tell us which three things changed rather
than leaving it up to us to dig through their code and figure it out.

We recently started automatically generating these particular reference
manuals as XML from the compiled source files in order to eliminate the need
for ANYBODY to try to keep track of changes to error codes and system
variables.

Our manuals are pretty big, ranging from just a few hundred pages to close
to 1600 pages.  Most of our documentation is revisions to what's already
there with minor additions peppered throughout a chapter or three.  It's
more prudent for us to work with what we have than to start from scratch.
Like I said, the developers often ask if there is something they can just
mark up with the changes.  After they do their scribbling on the chapter, we
take it from there, clarifying the writing, asking questions, filling in
information that is missing, asking more questions, and eventually producing
a manual.

Perhaps when writing about PC software it is easier to install the product
and beat on it and figure out what's different and what documentation needs
to be written and write it from scratch.  But that's not necessarily the
only way to do it.  Every company and documentation department has its own
way of doing documentation.  For four years I've been doing it the way my
company prefers, and it works for us.  If I change jobs, I'll have to learn
to do documentation somebody else's way.

Megan Rock
Technical Writer
FANUC Robotics North America, INC.

Views presented and opinions held are not necessarily those of my friends,
family, or employer.


> -----Original Message-----
> From: Barb Einarsen [mailto:barb -dot- einarsen -at- gnnettest -dot- com]
> Sent: Wednesday, May 16, 2001 10:35 AM
> To: TECHWR-L
> Subject: RE: format-monkeys, WAS: Interviewing Subject Matter Experts
> 
> 
> I have to chime in with a short story (aka rant). I once worked with a
> writer who thought it was absolutely OK, heck, the right 
> thing to do, to
> hand the developer the existing guide and ask them to 
> indicate how and where
> the changes appear in the new version. He would then work as 
> a 'technical
> typist' to implement their changes and send it out for 
> review. Hideous.
> Naturally, this is the same person who never did get a help 
> file to compile
> properly, I should know, I'd always have to fix it up the day 
> before the
> release.
> 
> Barb
 

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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See
http://www.infomap.com or 800-463-6627 for more about our solutions.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -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.