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.
Okay. Big long blurb on how I do things. A dense read, but worth it, if I do say so myself <grin>...
I publish in PDF from MSWord and use version control (Visual SourceSafe) with a fairly rigorous source tree/naming conventions. There are many products and several documents per product. Some products share documents. Some systems pick from a variety of products and documents. Most documents go through several revisions, especially in the year after first release. It gets complicated real fast without version control. But that's what makes it fun, right?
The published PDF files have the revision level in their filename, but my MSWord source documents do NOT. And should not, because it gets things confused and creates "stupid work"! Revision control of my source documents is left up to Visual SourceSafe (VSS). The PDF filenames include revision levels because those are the documents that escape the VSS realm.
My naming convention could not exist within a DOS 8.3 filename constraint. Because this is the new millennium, I believe there is no purpose for the 8.3 filename constraint.
However, only alphanumeric characters and the underscore are used. Spaces and other punctuation (including dashes (-) are not allowed. This is to accommodate the randomly crippling behavior of different FTP and other internet servers.
The PDF filename is derived from the MSWord source filename.
The MSWord filename is of the form:
<part_number>_<brief_doc_title>.doc
such as "500_00323_GC1202_UG.doc"
The PDF filename is of the form:
<part_number>_<revision>_<brief_doc_title>.doc
such as "500_00323_r103_GC1202_UG.doc"
The following terms are used in these two cases:
<part_number> is an 8 digit number of the form "500_xxxxx_" where 500 indicates a document and "xxxxx" is a unique document part number. An underscore (_) separates the "500" from the "xxxxx", and follows the "xxxxx". So this is EXACTLY 10 characters.
<brief_doc_title> is a mnemonic of the short title of the document, such as GC2012_UG. Recommended abbreviations are used, such as UG for User Guide, for brevity. Only alphanumeric characters and the underscore are used. Spaces are not allowed.
<revision> is a five character field of the form "rxxx_" where "r" is a single character alpha status flag ("d" = draft, "p" = prelim, and "r" = released); and "xxx" is the short form of our x.xx part number revision levels (for example, 1.03 would be 103). An underscore follows "rxxx". A draft of revision of 1.03 would be "d103_".
Yes, the filename is a bit long, but so what? It works well when PDFs are deployed in a variety of methods. From emailing to a big repository in one folder. The strictly defined <part_number> and <revision> portion of the filename enable scripts to easily process file operations based on wild card searches and sorts.
Revision levels in the PDFs ensure that staff and customers deal with the correct versions, and that one version does not overwrite another version of the document. This can reduce days of silly (or tragic) confusion for customers, technical support, executives and developers.
(Note: I wanted to remove a few underscores to shorten it up, but a certain QA manager -- no longer at the company -- wanted the underscores for greater clarity... Wasn't worth fighting over, so whatever...)
ROBOHELP X5 - SEE THE ALL NEW ROBOHELP X5 IN ACTION!
RoboHelp X5 is a giant leap forward in Help authoring technology, featuring all new Word 2003 support, Content Management, Multi-Author support, PDF and XML support and much more! View an online demo: http://www.macromedia.com/go/techwrldemo
---
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 lisa -at- techwr-l -dot- com -dot- Visit http://www.techwr-l.com/techwhirl/ for more resources and info.
