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.
Subject:RE: Is a new firmware version a "feature"? From:Beverly Robinson <beverly_robinson -at- datacard -dot- com> To:Techwr-l Posting <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Fri, 9 Aug 2013 09:21:43 -0500
Sorry for jumping in late-I'm on digest.
I don't understand the need to categorize new features by whether they need the new firmware. If I have been waiting for a certain new feature and will start using it as soon as possible, whether that feature needs new firmware is not important. From that point of view, your colleague's organization is marginally better because it places actual feature descriptions at the [h3] level instead of the [h4] level. I agree with you that colleague's penchant for forecasting information that's about to come is 1980's style tech writing.
How about this: add a text paragraph about Firmware x.y.z directly under the [h2], promote headings for each feature to [h3], and, where applicable, note that the feature requires the new firmware.
My co-techwriter thinks the fact of having a new firmware version for a product is a "feature".
I argue that it is not.
What the new firmware DOES, or what it enables/permits/allows can be new-or-improved features of the product, but the firmware version itself is not a feature as any customer would understand the word.
He also wants a presentation that I consider needlessly inflated and bumpf-ish.
In our current release notes, we publish a "New Features" section.
Each sub-section heading under "New Features" is a Product-Management-generated name for each new/updated feature, and that's followed by a paragraph or two of description for that feature.
New features that require a new version of firmware have a parenthetical note appended to the paragraph, like " (requires firmware 6.10.1) ".
Features that do not have such a note are implemented fully by software, and therefore are available to customers who choose not to update to the new firmware.
What the other writer wants to do is:
[h2] NEW FEATURES AND ENHANCEMENTS
[h3] Firmware x.y.z
Improves performance and provides support for some new features of product version A.B.C.
Note: f/w x.y.z is not yet validated by ACME Turtle-Watching Federation. If you require ATWF validation, continue to use f/w x.y.y, and forego some new features.
[h4] Features that require firmware x.y.z
a. Identify Snipes and tally by type (see description #xref below)
b. Identify Snarks and tally by type (see description #xref below)
c. Identify Boojums and tally by type (see description #xref below)
d. Corral Snipes, Snarks, and Boojums (see description #xref below)
[h4] Features that do not require firmware x.y.z
a. Scan for Snipes, any type (see description #xref below)
b. Scan for Snarks, any type (see description #xref below)
c. Scan for Boojums, any type (see description #xref below)
d. Report current combined count of Snipes, Snarks, and Boojums since <start> (see description #xref below)
e. Calculate average number of sightings per defined observation period <start> <duration> <number of repetitions> (see description #xref below)
[h3] Identify Snipes and tally by type
Blah, blah-blah blah blab description verbiage.
[h3] Identify Snarks and tally by type
Blah, blah-blah blah blab description verbiage.
[h3] Identify Boojums and tally by type
Blah, blah-blah blah blab description verbiage.
[h3] Corral Snipes, Snarks, and Boojums
Blah, blah-blah blah blab description verbiage.
[h3] Scan for Snipes, any type
Blah, blah-blah blah blab description verbiage.
[h3] Scan for Snarks, any type
Blah, blah-blah blah blab and some description verbiage.
[h3 Scan for Boojums, any type
Blah, blah-blah blah blab and much description verbiage.
[h3] Report current combined count of Snipes, Snarks, and Boojums since <start>
Blah, blah-blah blah blab and further description verbiage.
[h3] Calculate average number of sightings per defined observation period
Blah, blah-blah blah blab <start> <duration> <number of repetitions> and more description verbiage.
YOW! YOW! YOW! (end of his structure) YOW! YOW!
And here's how I would do it, given that a firmware version is not a feature in-and-of-itself.
[h2] NEW FEATURES AND ENHANCEMENTS
Little intro text....
[h3] Features That Require Firmware x.y.z
Note: f/w x.y.z is not yet validated by ACME Turtle-Watching Federation. If you require ATWF validation, continue to use f/w x.y.y, and forego the new features listed in this section.
[h4] Identify Snipes and tally by type
Blah, blah-blah blah blab description verbiage.
[h4] Identify Snarks and tally by type
Blah, blah-blah blah blab description verbiage.
[h4] Identify Boojums and tally by type
Blah, blah-blah blah blab description verbiage.
[h4] Corral Snipes, Snarks, and Boojums
Blah, blah-blah blah blab description verbiage.
[h4] Improved performance
Performance has improved for several operations, including wood chucking, dish spinning, and tiddly winking.
[h3 Features That Do Not Require Firmware x.y.z
[h4] Scan for Snipes, any type
Blah, blah-blah blah blab description verbiage.
[h4] Scan for Snarks, any type
Blah, blah-blah blah blab and some description verbiage.
[h4 Scan for Boojums, any type
Blah, blah-blah blah blab and much description verbiage.
[h4] Report current combined count of Snipes, Snarks, and Boojums since <start>
Blah, blah-blah blah blab and further description verbiage.
[h4] Calculate average number of sightings per defined observation period
Blah, blah-blah blah blab <start> <duration> <number of cycles> and more description verbiage.
YIKE! YIKE! YIKE! (end of my version of the same material) YIKE! YIKE!
I think that my version is more compact and straightforward, non-redundant, less convoluted, not requiring jumping forward and back between (sub-)lists and xrefs.
And my version does not make what I consider to be the erroneous (ok, flat-out wrong) assumption that a firmware version is a "feature" in-and-of-itself that a customer would care about.
Arguments in support of either case, or suggestions for some third option, gratefully entertained.
Thanks for reading this far. . . are you OK?
[Safenet legalese cut in favor of Datacard legalese]
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
