Re: TECHWR-L Digest - 23 Feb 1998 to 24 Feb 1998

[Marci Abels <mabels -at- CSIKS -dot- COM>]

Here are the responses I've received about wording regarding inoperable
features of the software. Mine are on the menus, so they do have to be
mentioned, if only to say Don't bother. :-)

There were lots of excellent suggestions, and we chose to go with the
simple, but elegant "Currently unavailable" Thanks to all the
suggestions from the list.

From: Anne Halsey
We've all faced this dilemma at one time or another.  I recently handled
it with a "What's different in this release" section.  I briefly
outlined the new features, linking to the appropriate sections of the
doc; briefly discussed what was no longer there or no longer
operational; and then briefly described "anticipated future
functionality" with no promises for when, how, or why.
It worked ... and my company was even commended for its refreshing
honesty.
From: Betty Champagne Guthrie
BTW, the software I am currently documenting has many of the same
problems that you are running into.  I've chosen a more light-hearted
approach, with various messages such as:
        We're working on it.  Check back later!
        Not now, Dear.  Maybe later....|
        Watch this space!
        This is still on our Wish List.
        This is still in the Tomorrow File.
        Still a good idea, but we haven't gotten this far yet....
and the like.  Of course, the software itself, and it's target audience,
are the main reason I can get away with this kind of thing.  The
software is called PigCare; it's for running -- are you ready for this?
-- pig breeding farms!
From: Carol Van Natta
Here at the gov't., we say "For possible future release," which lets the
users know that if they really like the feature, they'd better
call/write their reps about it or it probably won't get implemented.
From: Damien Braniff
"For future development" or similar (as you've done previously) is OK
for up and coming new features etc.  Anything that is now obsolete (for
whatever reason - no longer used, won't now be implemented) should, in
my opinion, be removed by the programmers.  I know this is very
dependent on timescales and the language used, how it's been written and
so on.  Still, if it has been written with menu changes etc in mind
(adding features etc) there is a good chance that it is structured so
that they would be easy to remove.  Programmers here agree (but being
programmers it's yes but...!)
From: John Cornellier
Where I work a lot of the interfaces, for reasons of homogeneity have a
4-byte  return code. Not all functions need 4 bytes of return. So we
might have something like:
Byte 1  error status
Byte 2  reader type
Byte 3  data
Byte 4  RFU
RFU means Reserved for Future Use. This way we don't need to explain
that really we just didn't need these bytes and padded them out.
Could you use a similar phrasing, even if you know menu items probably
won't be  used in the future? It's short-and-to-the-point, and entirely
non-commital.
From : Lucinda Metzger
Marci, we usually use something like "currently unavailable" or "not
available at this time."
From:    Kimberly Green <>
We use "Not available in Version 1.1" (the version number for the
release we are documenting). This is not a positive selling phrase, it
just states the fact and does not promise anything.
I am in a very similar situation. I am trying to document a constantly
changing software product with changing priorities and changing
schedules.  Does anyone have any tips for working effectively in this
situation?
From:    Suzanne Gerrior
I am in the same situation. I just say, "Feature is currently under
development and not yet available."
From:    "Bergerson, Carl A
To put it simply, don't mention items that are not in the current
version; that serves no useful purpose. If that information belongs
anywhere, it's got to be in marketing literature or the red herring
stuff for the investors.
As to the features being de-implemented, you should give your customers
one or two releases to plan for this. State in the release notes when
the feature will go away and what new features take its place. Provide
examples of old versus new code (procedures, whatever) unless it's
painfully obvious. Better yet, even if it's painfully obvious.
From:    Matt Craver
Our product is also constantly evolving, and there is no good way to
constantly revise documentation to keep up while writing new manuals.
Carl Bergerson had a good point that, if you can avoid a subject or
feature, it is best to not mention it. I use "Not Currently Implemented/
In Use" when this is not possible.  I also make very clear on the front
of the document which version of the software the document goes with,
and I give each document a revision number and date it on the cover.  In
this way, the customer knows that the information is current and
accurate at a particular level.
From:    Kathryn Poe
I've done software documentation for 4 years and it is always a moving
target but that's the nature of the beast. (That and the way programmers
sometimes look at you as if you came to steal their soul!) One thing to
add to Matt's comments- I also add a Release Notes page in each doc
stating specifically what is new in this release!  If you give the user
the highlights in plain English they won't be so thrown when they see
the message about "Feature Not Available in Release x.x". Tell them
Release X of this doc contains the following Changes and Updates: You
can now input the blue widget and the green widget is no longer
supported.

http://www.geocities.com/Heartland/Acres/2592/
CSI, Inc,
http://www.csi.com