Discussion on:

Working with contract tech writers for documentation needs

I have been a technical writer and technical documentation manager for over 18 years and I have to take exception to some of the advice you give in this article. If the company has a habit of documentation at each step of the software development process from inception through marketing through coding, a technical writer can come in near the end of a project and produce good end user documentation. However, the habit of documentation occurs in only about 3-5% of all software development companies. The rest document poorly if at all and when the technical writer comes in he or she is forced to go back to the engineers for explanations and the engineers are forced to go back and work through their code to answer those questions because nodocumentation was done at the time the code was written and usually there are no architectural design documents or detailed design documents either which might help to some degree.

A technical writer should be well acquainted with the technicalcontent of the field he or she is working in, have access to the entire corpus of documentation associated with the end product, have access to the engineers, marketing personnel, support personnel, etc., be able to run the code or portions of the code as they become available, know how to present the product to different audiences for different purposes and in different medias (i.e., print, electronic, multimedia, etc.), and have the support of management in obtaining the needed information, needed resources, etc.

Otherwise, you need to get an engineer who is also skilled in presenting information to users, installers, etc., to write the material, then hire yourself a good technical editor and a copy editor to prepare the material for publication either in print or electronic media.

There is much more that needs to be said, but I will stop at this point and welcome any comments.

This article does indeed miss the mark, at least
when hiring professional technical writers (not
$15-20/hr word processors/desktop publishers who
are often mistaken for technical writers because
no knows what else to call them).

Having been a documentation and training
specialist for almost 20 years, and a contractor
for most of those years, I am likely to turn down
a job where a manager is throwing money at the
problem six weeks before ship date. Yes, I was
deceived by easy money a couple of times. But
development teams that don't understand product
life cycle can't produce a product that I can
document to anybody's satisfaction, especially my
own. Bleating "oh, we'll catch it up in the next
version" doesn'timpress me. Neither does
overtime. I've often wondered whether these folks
are in business to make money or to spend it.

Part time is wonderful, both for me and for the
developers in the design phase. The method of
delivery for the documentation (paper/PDF/XML?)
belongs in the product design. Whether I build
button-pushing instructions or tutorials is also
part of the product design. Part time allows me to
juggle a couple of projects with different life
cycle time spans, good for me -- good for the
client(s).

Document development goes full time with unit
testing. The documents themselves and their mode
of delivery should be tested with the product when
it goes out for beta.

Unless end users were part of the design process,
a fixed price contract is guaranteed to create
work for the tech support people. Maybe that's
where the lousy documentation that seems to have

I agree with you hltwyman@yahoo.com - I , too am a technical writer and I also find that we are brought on-board much too late in the effort.
What I enjoy, however, is the chance to learn a new industry every time I write. I've written for the telecommunications industry as well as the energy industry. Each time I write, I have to learn the ins and outs of that business. True, it is difficult when you come on board and the state of the documentation is horrid. But this is not always the case.Sometimes the documentation is quite good as is, and we come in to make it better.

Hi there,
I wondered if it would be possible for we to pick at your
brain. I am a student in final year doing a degreee in
computer comms and networks.
I currently have to write a tender document for a given
scenario which needs to be madelike a contract for
terms and condiitions etc.
I wondered if you would have any example documents
of this type or would know where to get help.

This would be much appreciated.

Regards

Ben