Style for corrected bugs?

Subject: Style for corrected bugs?
From: "Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 14 Dec 2001 14:45:41 -0500

Johanne Cadorette is <<... editing release notes and have a list of
corrected bugs that are written like this: "When an entry was copied, it
wasn't possible to record its name using the name recorder." It could also
read: "When an entry is copied, it is now possible to record its name..."
I've seen both styles used, but am wondering if one is better than the
other.>>

Of the two, I prefer the second explanation, since it focuses on what the
reader can now do (the solution) rather than on what they couldn't do (the
former problem); identifying the former problem is less relevant than
alerting readers to the new possibilities because the problem no longer
exists. However, as a strong advocate of talking direclty to the reader, I'd
probably prefer "You can now record the name of any entry that you copy" or
something similar. You noted that not all bugs are that simple, so here's
another thought that works for pretty much all situations: create a table
with two columns, the first labeled "problem" (so readers can skim down the
list of problems until they find the one that used to affect them) and the
second labeled "solution" (so readers know how the problem has been solved).

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

Tarzan's rule of data processing: Never let go of one vine until you have a
solid hold of the next.--Anon.


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Collect Royalties, Not Rejection Letters! Tell us your rejection story when you
submit your manuscript to iUniverse Nov. 6 -Dec. 15 and get five free copies of
your book. What are you waiting for? http://www.iuniverse.com/media/techwr

Have you looked at the new content on TECHWR-L lately?
See http://www.raycomm.com/techwhirl/ and check it out.

---
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: RE: Steenkin budges
Next by Author: Best software for web site development?
Previous by Thread: Re: Style for corrected bugs
Next by Thread: Web Works Macros


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


Sponsored Ads