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