Re: Question re: managing document changes as software changes occur

Subject: Re: Question re: managing document changes as software changes occur
From: Beth Agnew <beth -dot- agnew -at- senecac -dot- on -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 14 Apr 2006 23:07:38 -0400

Laura, this should be very easy since you are working with the SDLC. The developers have a bug/fix system in place, all you need to do is parallel it for the documentation. On top of that, every change request for the software needs to be copied to you so that you can determine whether it will result in a documentation change. If you don't know about the software changes, it's pretty hard to keep the documentation up to date.

It is vital that you are seen as part of the development team. When they change the requirements, they must notify you. When specifications get
rewritten, they must notify you. The best way to do that is for you to be part of the meetings where those decisions are made, if possible, or
at least copied on e-mails that can alert you to changes. You are a developer too, an information developer. It might take some evangelizing
on your part, but you now have the mandate to ask for what you need. If requirements and specifications documents are reviewed (if they're not,
there are bigger problems...) then you also need to be one of the reviewers. As a user advocate, you can spot potential problems at these
earlier, easier to fix stages. Apart from that, as a reviewer you will at least know when there has been a new req or spec issued.

In a software development environment, I like to handle all changes to documentation by prioritizing them the same way as the developers handle
their bugs. Some are critical or important, and others are nice to have. Indeed, sometimes you can fix a reported software problem by issuing
changed documentation. Management loves that because doc fixes are seen as cheaper than code fixes. If your company uses bug tracking software,
get documentation added as a category, just like interface, configuration, etc. Make friends with customer support so you know what
problems are being reported, especially those that need to be covered in the documentation at some point. QA should also be your buddies. They
point out problems that will need fixing; the sooner you know about them, the better.

Don't forget to include documentation maintenance in your planning. Just as software must be maintained, documentation also needs to be
considered past the release date. Will you issue an updated edition? Will you only issue new docs with a new release, sending an Addendum
with an interim release? Once you develop a procedure on how the Software Documentation Life Cycle rolls out, everything else should be
straightforward. Are they using an iterative development methodology? Documentation has always been iterative, one version after the next.
It's very easy to match the software process with a parallel documentation process, and it's something development can wrap their
heads around, making it an easy sell to management, too.


Laura Johnson wrote:
> Anyway, 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...

Beth Agnew
Presenting "Podcasting & Vidcasting: The Future of TechComm"
at the STC Conference, Las Vegas, NV, 2 p.m. May 10, 2006

Professor, Technical Communication
Seneca College of Applied Arts & Technology
Toronto, ON 416.491.5050 x3133


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!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.

Previous by Author: RE: Software Translation Headaches
Next by Author: RE: It's PIZZA FRIDAY!!
Previous by Thread: Question re: managing document changes as software changes occur?
Next by Thread: Friday fun (one day late): Oh, really?

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

Sponsored Ads