Re: Documentation Process

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

> Currently, our programmers will get a request to make a software change 
> (an
> ICR - internal change request). They make the change to the program, and
> then they ask for a copy of a particular section in the user guide. They
> make the change in the document, and send it back to one of the
technical
> writers. The technical writers edit and make sure it has a style (if
they
> have time), and then overwrite the revised file back into the folder.

Why don't the technical writers just make the change? Why let the
engineers make it? 

> For example, three
> people can check out the same file, and each make their own changes to
it.
> Then, check it back in and have the three different sets of changes
tracked
> in one file so the technical writers will not have to look at three
> different copies and input the changes.

Word docs can do this. Frame can track changes, but it can't color code
them for each user. 

Might check out a version tracking system, like VSS. 

> I think this is impossible. My
> opinion is that our documentation process should be organized in a more
> efficient manner. It does not make sense to me for programmers to have
to
> write in the user guide, and have the technical writers edit their
work??

Yes, that is illogical. 

> In my last job, the programmers or support would submit an user guide
ICR.
> Then, I would try to make sense of the software change in my head, and
> update/write the manuals.  However, in my current company, there is not
> enough time for the technical writers to understand the material. 

<<shiver>>

Basically, you guys aren't tech writers, you're editors and coordinators.
So you need a process to manage everything here. You need a source control
system and some procedures to manage that. 

> We have
> project managers and trainers that interact with our audience (users) so
> shouldn't we interact more with project managers and trainers instead?

How about writers go out and interact with customers? That makes the most
sense. 

> If anyone out there works in a software company, would you please share
> your documentation process with me?  We are also trying to get more
control
> of release notes, specifications, and technical articles as well. Let me
> know your scenario, thoughts, or suggestions!!

Most places put the docs in the hands of the writers - who are responsible
for maintaining and managing the documentation content. You have a lot of
other people involved here. That in an of itself strikes me as a situation
rife with problems. You have a lot of hands inside the docs. THat's icky
no matter how you slice it. 

There is no real elegant way to manage a situation. However, you may look
into some kind of source control system. Be warned, these systems are
complex and require a fair amount of systems administration knowledge to
run and use them effectively. 

Good luck.

Andrew Plato 

__________________________________________________
Do You Yahoo!?
Make international calls for as low as $.04/minute with Yahoo! Messenger
http://phonecard.yahoo.com/

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

*** 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

A landmark hotel, one of America's most beautiful cities, and 
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

---
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.