Readme files with references to fixed bugs?

Subject: Readme files with references to fixed bugs?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 21 Aug 2001 08:53:38 -0400

Gilda Spitz reports: <<... our Documentation group also provides
readme/release note files... I have now been asked to provide much more
detail on each release. Apparently some of our users want a bug-by-bug
description for each minor release, so that they can decide whether to
upgrade or not... This is my opportunity to change the format from txt to
something with hypertext links... But I'm struggling to find a way to
provide the bug list.>>

If your audience actually requested bug descriptions, you now have a chance
to find out why they want them, how they'd use them, and thus, how to
present them. At a minimum, you should be able to create broad categories,
such as changes in the names of interface objects and functions that were
deleted because they couldn't be made to work in time for this current
release. Conversely, for modular software, you might want to organize the
bug fixes by module. Think about the audience's needs and use that to guide
the structure of your information. Once you understand that, you can pick a
technology that supports that use. One other thing to think about: Would it
be appropriate to include the bug information directly in the online help?
For example: "In the previous version, you had to stand on one foot and wave
both hands in the air, while using your lifted foot to press the Return key.
Although you can still do this, careful re-engineering of the software now
lets you remain seated while pressing Return with your foot. Note:
Lefthanded users should note that they must still use their right foot to
control the keyboard." <g>

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


Previous by Author: Writing proposals?
Next by Author: Adding new content to a recently released document?
Previous by Thread: Writing proposals?
Next by Thread: RE: Re\: Asimov - Assumptions, the audience and arithmetic - Rant ?


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


Sponsored Ads