TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> > 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.
TDean goes on to mention issues with multiple people updating the same
document at the same time and version control (asking for advice on this).
Andrew Plato wonders why programmers are writing the documentation, and also
offers some practical suggestions with regards to version control software.
He
also writes:
> 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.
I have worked in situations where the technical writers write docs, and also
in situations where the technical writers mostly do major editing and
managing of docs. When non-writers write, it is not always programmers - for
example it may be people in training, implementation or QA. This can be
helpful when you have non-writers who used to work at the same jobs that
current users are doing.
I almost worked for a place where a programmer also wrote the docs, but that
would have been me, replacing a programmer/technical writer as another
programmer/technical writer. I wasn't that desperate.
In general, I find that when non-writers are writing, there are usually
problems and the technical writer will spend a lot of time cleaning up docs.
When in the situation where non-writers write, I try to get them to send me
inserts or change documents, so that I can put in the information, editing
as I go (and not accidentally destroying index markers, etc).
In the absence of a version control program that will not allow multiple
simultaneous checkouts, I instruct people to work off the network and take
advantage of network file-locking - i.e., if they get a warning that the
file is locked, they do not edit the document until it is available.
TDean mentioned that one of the reasons programmers are writing docs is that
after the coding is finished, there was not enough time for the writers to
learn the material that needs to be documented, that ICRs are sent out after
the code is finished.
The programmers should have some idea what they are going to program before
they start. You should try to find this information out at the same time and
start writing before they are finished coding. For example, there may be
design specification documents or customer request forms - if you have
access to these, you can start writing docs and learning what the product is
supposed to do before the code is finished. Then once the code is finished
you can update your docs to the finished reality and take screen captures.
If there are no design docs or other written planning/request documents,
there must be some way the programmers are finding out what they are
supposed to do - maybe there are planning meetings you can sit in on, an
e-mail distribution list you can get on, etc.
Besides regaining control over the docs, writing before coding is finished
helps get out the documentation sooner. If there is a Q/A department, you
can probably finish the docs at the same time as Q/A is finished. Even
better, Q/A may be willing to help test your docs - they will probably be
happy to have some documentation going into testing.
This material is intended for the use of the individual
to whom it is addressed and may contain information that
is privileged, proprietary, confidential and exempt from
disclosure. If you are not the intended recipient or the
person responsible for delivering the material to the
intended recipient, you are notified that dissemination,
distribution or copying of this communication is strictly
prohibited.
If you have received this communication in error,
please contact the sender immediately via e-mail and destroy this message
accordingly.
*** 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.
