Re: Address this. . .

Subject: Re: Address this. . .
From: Bill Swallow <techcommdood -at- gmail -dot- com>
To: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com>
Date: Sun, 14 Mar 2010 23:55:56 -0500

> This is one of those "we've always done it this way" things.

How's that definition of insanity go again? ;)

> Separately, we do have a trouble-ticket system for
> customers, and they can indeed look up the status
> of their own issues - not sure what access they
> have to other customers' issues. There are privacy
> concerns - we can't be a source of competitive
> "business intelligence" among our competing customers.

Customers shouldn't see each other's submitted issues. I'm sure it's a
breach of support contract. But if they can see their own, great!

> But while those customer-generated issues are brought
> into the working database (MKS) that developers and
> testers use, there are also lots more bugs that need
> to be tracked, including:

Those are internal and should be treated as such. From my work history
and IMO, I would not write up the fixes to internal bugs. I also
wouldn't like to browse the back of my Froot Loops box to see that
while developing the recipe they discovered the cereal to contain
large amounts of lead, asbestos, and mercury, but it's all better now.

> Many of those never see the light of day outside
> the company, while others - that no customer
> specifically asked about - are made public because
> they could affect customers and we want them to
> hold off, or employ workarounds until we can kill
> a bug.

Those would be best communicated as a caution but used sparingly. I'd
save it for the real bad "murder death kill" bugs. Otherwise let your
tech support giggle while customers call asking how to use the three

> Anyway, I know that some will say that any "what's new"
> stuff should go in the main docs - for me that's
> mostly all WebHelp - but I don't use such docs for
> announcements. I just write 'em matter-of-factly
> as "this is the way it is as you find it". Yes, I
> do wave a flag if there's a change between versions
> that would have a significant effect on existing
> customers/users, but that's on a per-activity basis.
> "The xyz feature might affect your existing scripts..."
> "ABC algorithms no longer default to xxx key-size,
> for security reasons." Or, similarly, "The evolving
> FIPS 140-2 standard now prohibits such'n'such algorithms
> or key sizes, therefore the system makes them unavailable
> if it is operating in 'FIPS-mode'." "Versions of JJJ
> older than x are no longer supported."

That's a fine approach for release notes. I've seen release notes
documents grow from 2-3 pages to over 120 (no lie) because people kept
finding new info to put in there. Overcommunication is just as bad as
undercommunication. Blurb it up in the release notes, and save the
"how it is" for the main docs.

Bill Swallow

Twitter: @techcommdood

Available for contract and full time opportunities.

STC Ideas:

Use Doc-To-Help's XML-based editor, Microsoft Word, or HTML and
produce desktop, Web, or print deliverables. Just write (or import)
and Doc-To-Help does the rest. Free trial:

Explore CAREER options and paths related to Technical Writing,
learn to create SOFTWARE REQUIREMENTS documents, and
get tips on FUNCTIONAL SPECIFICATION best practices. Free at:

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -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 admin -at- techwr-l -dot- com -dot- Visit for more resources and info.

Please move off-topic discussions to the Chat list, at:


Address this. . .: From: McLauchlan, Kevin
Re: Address this. . .: From: Bill Swallow
Re: Address this. . .: From: Gene Kim-Eng
RE: Address this. . .: From: McLauchlan, Kevin

Previous by Author: Re: Address this. . .
Next by Author: Re: Address this. . .
Previous by Thread: RE: Address this. . .
Next by Thread: RE: Address this. . .

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

Sponsored Ads