Re: How to produce document IDs
Hi,
Where I work, we have a growing set of documentation to support the
software the company produces, where we are presently supporting
documentation for two major versions of the software, several minor
versions, plus some custom plug-ins.
We need a method for creating unique document IDs, where we can easily
identify the software version, the date the documentation was produced,
and some way of describing any customizations. It may sound as if we
could easily devise a code to describe these variables, but what we are
looking for is an industry standard, if such exists, for resolving this
problem.
We've gone a few rounds on this issue in the past, and I think that with the exception of a few holdouts most of us have moved in the direction of the KISS principle.
Give each document a sequential identifier that itself contains no semantic information but that keys to a spreadsheet or relational database record with all the variables spelled out.
The reason you don't want any semantic information in the number itself is that YOU ARE THE ONLY PERSON WHO WILL UNDERSTAND IT! Call this a lesson learned, but one that a lot of techwrlers have learned independently. Even if you have a committee spend hours devising a clever coding system, most of the committee members will forget about it in three months and the rest will have moved on to other assignments or other companies in six months. Once you're gone, it will take a crytographer to decode the system.
In the spreadsheet or database (depending on how sophisticated you need to get to support search capabilities), you can identify software version, document revision, dates, owners, authors, reviewers, and on and on and on. Again, I encourage you to limit the number of required fields to the minimum number that people are actually going to need and use in the future. If you want to have a bunch of interesting and informative but otherwise unnecessary stuff in optional fields, go for it. But know that they are not going to still be in use a year from now.
Wholly apart from the document number, it is sometimes useful to have printing information, such as the date printed, the size of the print run, and the run number (if the same document goes through multiple printings). These are features only of printed docs, of course, and would be silly to include in something you distribute electronically.
The date and run size are usually encoded on the last page printed (may or may not include the covers, as sometimes people print long runs of generic color covers). You will often see such lines on forms, booklets, and other sorts of documents, in small print in the bottom margin. Typically the line starts with the run size in hundreds (c) or thousands (m) followed by the date in yymm or yymmdd format. So you might see "2m0409" for two thousand copies printed in September 2004, for example. This might be followed by the document number that keys to the database, or that might be somewhere more prominent, like the copyright page or title page.
The run number is what you see on the copyright page of many books. Typically you will see a line that looks like this:
A B C D E F G H I J 10 9 8 7 6 5 4 3 2 1
This means that the initial set of printing plates (A) is in use and this is the first printing (1). When new plates are burned, the A will be masked on the negative. (This may indicate that minor corrections were made, by the way, such as fixing typos or adding a sentence that takes into account the latest hurricane or the most recent terrorist incident.) When additional copies are printed from the current set of plates, though, the letter does not change but the pressman will scratch off the lowest number (1 in this example).
The likelihood that any document written by a techwrler will require either of these conventions is minuscule, but if you were ever curious about these strange markings, that's what they're about.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ROBOHELP X5: Featuring Word 2003 support, Content Management, Multi-Author
support, PDF and XML support and much more!
TRY IT TODAY at http://www.macromedia.com/go/techwrl
WEBWORKS FINALDRAFT: New! Document review system for Word and FrameMaker
authors. Automatic browser-based drafts with unlimited reviewers. Full
online discussions -- no Web server needed! http://www.webworks.com/techwr-l
---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- techwr-l -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.
References:
How to produce document IDs: From: Brian Shaw
Previous by Author:
Re: Interesting read...
Next by Author:
Re: Pagination issues - pros & cons
Previous by Thread:
How to produce document IDs
Next by Thread:
RE: How to produce document IDs
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads