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.
The company I work for prides itself on being responsive to client needs.
The owner of the company is one of the principle programmers. Mix those to
things together and it's not uncommon for the owner to visit a client site
and the program to change on the plane trip back. Uuugghh! Try keeping up
with that! Up to a little over a year ago documentation was considered a
necessary evil (although, sales made a big deal about our context sensitive
help to potential clients). As long as clients weren't too vocal with
complaints, the docs were considered just fine. We literally had just enough
time to swap out screens shots and change the version number and add a new
feature or two between releases. It was bad enough that the program would
change right up to the release date, but most of the time we were never told
of the changes. We have to stay in constant contact with a programming staff
of about 30 to monitor changes.
There were three tech writers and our boss was a VP with a number of other
responsibilities. No one was really try to develop and improve our docs.
The value of good docs began to be recognized and about 15 months ago I was
asked to manage the doc dept. Since then we have gone from the three of us,
to myself and seven full time writers. We have moved from Word to FrameMaker
and are single sourcing our online through WebWorks. We have changed our
approach from function based to task based, developed a style guide, and
went from photocopied and tape binding to perfect bond manuals. But guess
what's the same? The program still changes right up to the end and we have
to figure out what those changes are.
So this is what we are doing to attempt to deal with the problem:
1. Instead of jumping in and starting to write like mad, we are trying to do
more up front planning. We are starting with a detailed doc plan, then
creating an outline, then a doc shell before we start documenting individual
tasks/features. We are trying to gather more information up front and track
changes to the program. We are waiting later in the process to actually
start writing to avoid as many "redos" as possible.
2. We are requiring programmers to sign off on the doc plan. In doing so
they agree to provide us with the necessary information about both program
changes and features in a timely manner and review the docs for accuracy. No
sign off, no docs. This forces the few programmers that feel they can't be
bothered to explain to their boss they think that providing info to
documentation is beneath them (one programmer actually told one of my
writers, "Explaining to you how this works is the unpaid part of my job").
3. The doc plan has a timeline that works backwards from the ship date. The
deadline for changes is established then. Any changes after that date won't
make it in the docs.
4. When a final technical review is made, the programmers must sign off on
it stating that they have read the docs THOROUGHLY and vouch for their
accuracy. If they don't sign off, no docs. Their names are included as
technical reviewers along with the names of the writers in the docs. It's
amazing how much ownership they take when their name is on it.
OK, sounds like tough talk, but we have yet to fully go through this
process. We were developing it during our last release cycle. Those docs are
at the printer as we speak. For the next go around we will be using this
process. We'll see what happens.
*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available 4/30/01 at http://www.devahelp.com or info -at- devahelp -dot- com
IPCC 01, the IEEE International Professional Communication Conference,
October 24-27, 2001 at historic La Fonda in Santa Fe, New Mexico, USA.
CALL FOR PAPERS OPEN UNTIL MARCH 15. 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.
