Re: Documentation Process

Subject: Re: Documentation Process
From: Andrew Plato <intrepid_es -at- yahoo -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 16 Aug 2001 14:36:17 -0700 (PDT)

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


Follow-Ups:

Previous by Author: Re: Biggest salary cut you've taken?
Next by Author: Re: Contractors: Run Credit Checks for Questionable Customers?
Previous by Thread: RE: Tina's firm's ocumentation Process
Next by Thread: RE: Documentation Process [long]


What this post helpful? Share it with friends and colleagues:


Sponsored Ads