Re: Is it just me? S/W doc question

Subject: Re: Is it just me? S/W doc question
From: Tim Altom <taltom -at- IQUEST -dot- NET>
Date: Thu, 29 May 1997 09:36:07 -0500

At 09:56 AM 5/29/97 EST, you wrote:

>When you're documenting an application, and it changes, is there
>a procedure in place to notify all concerned? Or do you just
>find out after you've written the chapter, and then you have to
>rewrite it?
<cut to preserve bandwidth>
>Anyway, I just wanted to know if others are facing this
>difficulty. I suspect they are. I hope I'm not the only one!

No, far from it. And I think the problem is often worse for internal
captives, because they're seen as fellow drudges, not as expensive contractors.

Well-managed projects pass around some kind of paperwork, a "change notice"
or "ECN", or something similarly named. Or at least they make the forms
available to you in a binder or booklet. Without such a formal channel
you'll have to create an informal one. Or find out later and blame the
organization for not keeping you informed. This is a constant problem in
software development, especially when the release date approaches and
everyone begins to stay at the office later and later.

You can make some shock pads for yourself, BTW. Try to anticipate what will
change and what probably won't. The developers can often give you an insight
into what's volatile. Try to write in modules with as few references as
possible. Use a tool like FrameMaker that automatically updates all
references throughout the doc. Reference commonly-used screen shots instead
of embedding them. Chunk information. Plan thoroughly at the beginning. Have
a strong template. These things are damage control for changes; they limit
the potential havoc a major change can create. Used well, they can reduce
your change headaches by a considerable amount.
>This is the problem with having worked on only one project and
>for only one company -- I've officially been a tech writer for
>four years, but it's almost like the same year of experience
>repeated four times. I'm glad y'all are out there to share your

I think you're right. It's fast reaching the point that software documentors
are moving on as readily as programmers. And although that seems threatening
and scary, it's actually a plus in such a road-runner environment. You see
much more of the world. I like it a lot better.

Tim Altom
Vice President, Simply Written, Inc.
317.899.5882 (voice) 317.899.5987 (fax)
FrameMaker support ForeHelp support
FrameMaker-to-HTML Conversions
HTML Help Consulting and Production

TECHWR-L (Technical Communication) List Information: To send a message
to 2500+ readers, e-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send commands
Search the archives at or search and
browse the archives at

Previous by Author: Re: desparately seeking java-based help
Next by Author: Re: desparately seeking java-based help
Previous by Thread: Re: Is it just me? S/W doc question
Next by Thread: Is it just me? S/W doc question

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

Sponsored Ads