RE: How to produce document IDs

["Brian Shaw" <bshaw -at- activplant -dot- com>]

Hi,
I just wanted to say thanks to Dick for his prompt response to our need
to create meaningful document IDs. The advice seems sage, so we'll put
it into effect soon.
Many thanks,
Brian Shaw
Documentation Specialist
Activplant Corporation
London, Canada

-----Original Message-----
From: Dick Margulis [mailto:margulisd -at- comcast -dot- net] 
Sent: Wednesday, September 15, 2004 10:24 AM
To: Brian Shaw
Cc: TECHWR-L
Subject: Re: How to produce document IDs



Brian Shaw wrote:

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

-------------------------------------------------------

The information in this email is confidential and is
intended solely for the addressee. Access to this email
by anyone else is unauthorized.

If you are not the intended recipient, any disclosure,
copying, distribution or any action taken or omitted to 
be taken in reliance on it, is prohibited and may be
unlawful.  Please contact privacy -at- activplant -dot- com for 
cases where you have received this email and were not 
the intended recipient.



^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

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.