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.
Laura Johnson wonders: <<I've been tasked with coming up with a process
that makes sure that changes made to the software design are reflected
in the technical documentation. Meaning, we'll be having a Requirements
doc, a Specifications doc, etc., but, as the software design process
moves along, change requests come through and the software is
changed....but the documentation rarely is.>>
Welcome to life in software development. <g> The key thing is that you
seem to have a process in place that uses "change requests" rather than
simply random mutation of the software. If you can find a way to
receive the change requests, then you will be every bit as aware of the
status of the software as the developers are. When something changes,
add it to your list of things to check against the documentation.
Of course, first you have to get the documentation up to date:
<<What we're dealing with here is an application that is now 2 years
old and there are literally several thousand change requests that have
been implemented...but the documentation never reflected those changes.
So when you look at the original documentation, it's almost completely
different from the current version of the software. The original
documentation is pretty much useless.>>
If that's really the case, then you need to restart your documentation
from scratch, and use the old documentation almost exclusively as
reference material. That is, you can use it to research how something
was once supposed to work, and use that knowledge to provide insights
into how it currently works--or at least to serve as the basis for
informed queries to the developers. Some of the interface won't have
changed, so you can copy and reuse that original documentation.
One slightly more efficient way to work is to find out what aspects of
the software have been frozen semi-permanently, which ones will soon be
frozen, and which ones are still being "made up as we go". The more
frozen the module, the more effort you should devote to documenting it.
There's little point documenting something that you'll have to change
daily, but a lot of value in documenting something that won't change
much.
Inform the development manager that the documentation will be ready 2
weeks after the final interface freeze--with "2 weeks" being replaced
by the time that will actually be required for you to do a final
run-through of the documentation so that you can check every line
against the software to detect changes that slipped through the
process.
<<but we're starting to develop a new application so they want me to
put something in place so things don't get out of control again.>>
Two useful references are Alan Cooper's book "The Inmates are Running
the Asylum" and his Web site (www.cooper.com). The correct way to
design software is to spend a lot of time up front prototyping the
software interface based on the problems you're trying to solve for its
users. It makes no sense to actually start coding before you know what
you're trying to achieve. While you do this, have the developers
devoting some skull sweat to the thorny algorithms they'll need to
develop to solve those problems (i.e. so you aren't wasting their time
while you plan).
It's important to note that interfaces take hours to develop, whereas
algorithms (the plumbing below the interface) takes days or weeks to
develop and troubleshoot. Solve the interface first, and you can begin
documenting it because it won't have to change much, if at all. The
plumbing can evolve a hundred times, if necessary, but if the interface
is stable, you can keep working while the plumbers plumb.
The objection that's often raised is that nobody works this way, or
that it's impossible to foresee all eventualities. Remind them that
architects and engineers have worked this way for (respectively)
millennia and centuries for one reason: it works better than simply
figuring out the design as you build something. Programmers sometimes
like to put on airs and proclaim how mystical their work is. Nonsense.
There's certainly an art to solving programming problems, but
programming is as rigorous an activity as engineering, and a good half
of the problems we face in using software result from programmers who
wave their hands and make airy statements instead of buckling down to
do the hard work.
Here's the hard part: Once you have a functional and effective design,
you stick to it. No matter how many cool ideas you come up with along
the way, you resist the temptation to implement them in the current
version of the software unless they're crucial for the current version
to work.
New features are what new releases are for. If the managers balk,
remind them that new releases represent an ongoing series of income
opportunities for the company, whereas trying to cram every imaginable
feature into the current version represents nothing more than an
ongoing series of bug fixes. Ask them which is better for the bottom
line and their career. They'll get the hint.
WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today!. http://www.webworks.com/techwr-l
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at http://www.DocToHelp.com/TechwrlList
