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, 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.
--Beth
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 http://www.tinyurl.com/83u5u
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
