Advice on doc updates

Subject: Advice on doc updates
From: "Jim Morgan" <jim -dot- morgan -at- portalplayer -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 1 Oct 2001 11:43:34 -0700

Hello all,

After years of managing in a scientific organization, I'm now in an embedded
systems company and trying to assess best practices in this industry.
Specifically, we produce chips, development boards, and firmware for digital
audio equipment.

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:

--Consider the first complete version as frozen, and capture all changes
only in errata and app notes (with links to those from affected topics).
--Consider the document as living, but publish only the most recent version
of a given topic along with its revision history.
--Consider the document as living, but publish all versions of each topic
along with revision histories.

Have I missed other approaches? More to the point, is there an "industry
standard" approach? If not, what approach do you use and why?

Thank you for your time,

Jim Morgan
Technical Communications Mgr.
PortalPlayer, Inc.


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

+++ Miramo -- Database/XML publishing automation. See us at +++
+++ Seybold SFO, Sept. 25-27, in the Adobe Partners Pavilion +++
+++ More info: +++

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 for more resources and info.

Previous by Author: RE: The Wave of a TW's Future: (was RE: Tools & Technologies)
Next by Author: Re: Need help please
Previous by Thread: Caps lock... (was Typos of the Week!)
Next by Thread: Doxygen

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

Sponsored Ads