RE: Undocumenting documented features

Subject: RE: Undocumenting documented features
From: "Gilda Spitz" <gspitz -at- longview -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 9 Aug 2001 09:41:31 -0400

Thanks for the feedback. Here are a few clarifications.

>>> Does that mean they have to pay more to do the same thing?

Nope, all part of the same install package. The old functionality is in
our client, the new is in a new Web-based application that is far more
accessible and easy to use.

>>> There may be existing users who depend on the functionality to
execute macros, run plug-ins,
or have documented workflows.

Nope. Upper management gave me the OK only after checking to see if any
existing customers use it. They don't. I'm just concerned about new
customers who see the menu picks and dialogs, or old customers who
suddenly decide to experiment.

>>> many, if not most, software packages have undocumented features

Actually, that's the point of my question. I wanted to know how common
it is to have undocumented features; and if it IS common, is it so
terrible? This dilemma reminds of the kid who wants to do something all
his friends are doing. The mother says "So, if Jimmy jumped off the
roof, would you want to do that too?"

>>> What is your worry about the documentation disappearing?

I would love to get rid of 100 pages in the Ref Guide, if possible, not
to mention the corresponding number of HTML pages in the online help.

>>> New users would unlikely stumble across the old functionality as the
documentation will point
them to the new functions.

Yes, they would see the old functionality very easily. For example,
without going into technical details, when you create a new item,
there's a drop-down list giving you a choice. If I eliminate the
obsolete items, there will be two choices in that drop-down list that
will have no explanation.

>>> Older users will know what they are doing and will
probably have older reference manuals kicking around if they have need
of help
with the older functions.

This is true. I guess I could add a note telling them to check older
manuals if necessary.

Thanks for your feedback. I'm still receiving lots of e-mail from other
techwr-lers. I'll let you know how it turns out.

Gilda Spitz
Manager, Documentation
Longview Solutions Inc.


-----Original Message-----
From: edunn -at- transport -dot- bombardier -dot- com
[mailto:edunn -at- transport -dot- bombardier -dot- com]
Sent: Thursday, August 09, 2001 9:21 AM
To: Gilda Spitz; TECHWR-L -at- lists -dot- raycomm -dot- com
Subject: Re: Undocumenting documented features




I'd have to disagree with Gilda and others on this thread. I think that
there is
nothing wrong with leaving the functionality in the program, but
removing the
documentation.

Just look at functions such as Freeze Pagination (Esc p z) in
FrameMaker. While
undocumented since about version 5, and the fact it doesn't work
entirely as one
would expect, there are still uses for it.

What raises questions in my head is the "they can do the same tasks,
more easily
and efficiently, with another product from our company". Does that mean
they
have to pay more to do the same thing? I would be very unimpressed if
software I
used stripped functionality and then made me buy a separate package. The
norm, I
would think, is that with each successive release FEWER add-on products
and
packages should be required as the product matures.

Removing functionality from a program is a dangerous thing. There may be
existing users who depend on the functionality to execute macros, run
plug-ins,
or have documented workflows. Forcing them into rewriting/reworking
their custom
solutions along with upgrading the software may cause them to jump ship
to
another product. If you remove it without warning them, you may incur
their
wrath. They'll downgrade to the older software to meet current demands
and then
out of [spite/revenge/justified worry about support] move to another
product for
future needs.

In any case, look at it this way: many, if not most, software packages
have
undocumented features. Either because of newer overlapping
functionality, or the
feature never made it to prime time. But many advanced users may have
found ways
to leverage these 'hidden' features in ways the original programmers
never
envisioned.

What is your worry about the documentation disappearing? New users would
unlikely stumble across the old functionality as the documentation will
point
them to the new functions. Older users will know what they are doing and
will
probably have older reference manuals kicking around if they have need
of help
with the older functions.

Eric L. Dunn



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

*** 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.


Previous by Author: Undocumenting documented features
Next by Author: RE: Undocumenting documented features?
Previous by Thread: Re: Undocumenting documented features
Next by Thread: RE: Undocumenting documented features


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


Sponsored Ads