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