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.
Jim Morgan is working for <<... an embedded systems company... The issue at
hand regards updates to engineering documents, specifically a large chip
databook and our API/SDK documentation. We publish in HTML and PDF to CD
(soon to an extranet) and therefore can produce updates with immediacy. In
reviewing other companies' documentation, I have observed or thought of
three approaches regarding updates:>>
Think of this from the user's perspective: If they're trying to use some of
your documentation for the first time, with a currently shipping chip that
is in its final form, they want the final version of the docs so they won't
have to read through half a dozen update documents and integrate them in
their heads to learn the final state of a given aspect of the chip or API.
On the other hand, if the chip is undergoing rapid changes as the user is
developing a product based on the prototype chip, they need to obtain timely
updates on anything that's changed since the last time they read the docs.
To satisfy both needs, you must produce two forms of documentation: the
current, "live" document that integrates all the changes, and an Appendix
(or second document) that lists all changes and their implications. Ideally,
that second document should be designed to follow how the users will look up
the information; for example, if you change the properties of a register on
the chip, you might file this under the register name, whereas if you change
the number of registers, you might file this under "number of registers" or
"on-chip storage". Some kind of e-mail newsletter might also be very
appropriate; for example, if I were programming some obscure element of a
chip and delving deep into the underlying logic, I'd want to know asap when
that logic changed so I wouldn't waste days of my time programming the wrong
thing, in the wrong way.
While these recommendations seem reasonable to _me_, I'm suggesting them on
a purely theoretical basis; I don't design things with chips in them, and
haven't programmed a chip in more years than I'd like to recall. That being
the case, you should confirm that my suggestions match the reality
experienced by the users of your products. It's quite likely they have at
least slightly different needs than the ones I've inferred.
--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
Planning to attend IPCC 01, October 24-27 in Santa Fe? Sign up by
October 3 and get a substantial discount! Program information,
online registration, and more on http://ieeepcs.org/2001/
+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: http://www.axialinfo.comhttp://www.miramo.com +++
---
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.
