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.
> 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
seashells.
> 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.
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: http://www.doctohelp.com
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: http://www.ModernAnalyst.com
---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-
