RE: Undocumenting documented features?

["Gilda Spitz" <gspitz -at- longview -dot- com>]

Geoff Hart suggests that I add the following note to our documentation:

>>> We recommend that you no longer use this
function, because it will sterilize your children, cause unpredictable
and
irreversible weight gain, and lead to IRS audits.

I love it! Thanks for my laugh of the day.

Seriously, though, thanks for your thoughtful response. 

>>> On the assumption that everyone has the new product:

Yes, that's a valid assumption.

I agree that the best course of action would be to remove the feature
from the software. I'm convinced - but I don't know if I can convince
the programmers!

Gilda

-----Original Message-----
From: Hart, Geoff [mailto:Geoff-H -at- MTL -dot- FERIC -dot- CA]
Sent: Thursday, August 09, 2001 11:22 AM
To: Techwr-L (E-mail); Gilda Spitz
Subject: Undocumenting documented features?


Gilda Spitz reports: <<We have a very large Reference Guide that
describes
all the commands and functions in our software. There's one area of the
functionality that our customers don't use any more (because they can do
the
same tasks, more easily and efficiently, with another product from our
company).  The documentation for the obsolete functionality takes about
100
pages of the Ref Guide, and lots of HTML pages in the online help. >>

This suggests that you're assuming all customers have that "other
product".
If that's not a certainty, then you should leave the old information in
the
manual for those who still need it. On the assumption that everyone has
the
new product:

<<I've wanted to get rid of those pages for a long time, but only if the
functionality was stripped out of the software. After much pleading, I
finally got upper management to agree in principle - but it turns out to
be
more trouble than it's worth, from a programming point of view.>>

That may not be a justifiable conclusion, or may at least be
shortsighted.
If the old functionality remains part of the software, its presence will
eventually cause maintenance nightmares once the original team who
programmed it has gone on to greener pastures or has forgotten what they
programmed, how they did it, and why they did it that way. I'm told by
reliable sources that one reason Microsoft never fixed bugs in its
autonumbering feature is the fact that nobody understands the code
anymore
and how it interacts with the rest of the code. (The latter is, I
believe,
called "regresssion testing".) This is also why Adobe took so long to
get
PageMaker revised and started from scratch with InDesign, and why Corel
took
forever to get WordPerfect working right. Unless the programmers can
testify
that the obsolete functions don't affect any of the rest of the code,
keeping the obsolete code in place will eventually come back to haunt
you--and of course, if its presence doesn't affect the rest of the code
at
all, then they're probably lying about the amount of work required to
remove
it. You note:

<<So now they've asked me to just delete the pages in the documentation,
even though the functionality still exists, and still works. But this
means
that certain dialogs and menu picks would still appear in the software,
with
no explanation in the docs.>>

At some future point, some revision to the remaining features or
addition of
new features will lead to the following situation: the software will
have
arrived at a specific "mental" state (with specific data and program
code on
the stack and elsewhere in memory), a user will invoke the decades-old
code
that hasn't been tested for compatibility with the newer code, and an
unforseen conflict between the old assumptions and the new reality will
cause a major crash. If that crash loses data or endangers someone's
life or
job, your customers are going to be mad enough to chew nails and your
programmers will suddenly find themselves in the unenviable position of
having to reverse-engineer ancient code to find out the source of the
problem and fix it on a tight deadline--probably by removing the ancient
code, which they should have done in the first place, and could have
done
much more easily now than in 10 years. At a minimum, the programmers
should
easily be able to identify all menu calls and dialog boxes that refer to
the
old code, and replace the target for those calls with a dialog box:
"This
function is no longer supported. Please use NewSoft version 7 or later
to
accomplish the same goal."

In any event, it's easy enough to change the documentation: simply
insert a
note that "although these features remain in the software, they're no
longer
supported because we've replaced them with a newer, easier solution
[provide
a cross-ref or other details here]. We recommend that you no longer use
this
function, because it will sterilize your children, cause unpredictable
and
irreversible weight gain, and lead to IRS audits. If, despite our
warnings,
you must still use this code, see the online help [details on how to get
there] for details." Repeat the same warning in the online help. This
accomplishes three goals: shortening the printed docs, letting readers
know
that a solution is available online if they need it, and warning them
that
at some point the functions may blow up in their faces.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

"The most likely way for the world to be destroyed, most experts agree,
is
by accident. That's where we come in; we're computer professionals. We
cause
accidents."-- Nathaniel Borenstein

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

*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at http://www.devahelp.com or info -at- devahelp -dot- com

A landmark hotel, one of America's most beautiful cities, and
three and a half days of immersion in the state of the art:
IPCC 01, Oct. 24-27 in Santa Fe.  http://ieeepcs.org/2001/

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.