RE: Is a new firmware version a "feature"?

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.

Beverly
= = = = = = = = =
Original message:

Message: 1

Date: Thu, 8 Aug 2013 11:28:35 -0400

From: "McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com<mailto:Kevin -dot- McLauchlan -at- safenet-inc -dot- com>>

To: "TECHWR-L (techwr-l -at- techwr-l -dot- com<mailto:techwr-l -at- techwr-l -dot- com>)" <techwr-l -at- techwr-l -dot- com<mailto:techwr-l -at- techwr-l -dot- com>>

Subject: Is a new firmware version a "feature"?

Message-ID:

<D1E2C829C5011E4A84DAF8A184DD7CDA030AF2422D -at- BEL1EXCH02 -dot- amer -dot- sfnt -dot- local<mailto:D1E2C829C5011E4A84DAF8A184DD7CDA030AF2422D -at- BEL1EXCH02 -dot- amer -dot- sfnt -dot- local>>



Content-Type: text/plain; charset="us-ascii"



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.

Learn more: http://bit.ly/ZeOZeQ

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

Next by Author: RE: Is a new firmware version a "feature"?
Previous by Thread: Re: Is a new firmware version a "feature"?
Next by Thread: Re: Is a new firmware version a "feature"?


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


Sponsored Ads