RE: PDF filenames - include release designation ?

["David Artman" <david -at- davidartman -dot- com>]

   The practice I've followed at multiple companies (often being the one
   to actually ask for and create a standard for the first time!):

   Format:

   <product>_<v>-<r>-<m>[-<b>]_<manual-title>_<part-number>-<revision>.<ex
   tension>

   Example:

   Java_6-3-12_Programming_Reference_5555-66666-01.pdf

   Reasons:

   * When considering the 'natural' title of the doc--which should match
   its file name, yes?--underscores replace spaces; hyphens replace
   periods; NO other 'special characters' allowed(!!!) - Prevents a URL of
   the file from being unreadable with a bunch of %nn% character
   substitutions. Also helps (some) with file portability between (some)
   operating systems (sometimes). :-)

   * Product first, for file-name sorting and basically because it's
   logical.

   * Version, Release, and Modification (and optionally Build) next, again
   for file-name sorting (and logic). I'll leave it to you to decide if
   you want leading zeroes for each digit or not--there's little
   benefit... except when looking at a HUGE list of files covering more
   than 10 versions, which then won't sort properly in most OSes.

   * Manual Title could be almost anything, but imagine strings of the
   form: "Operation", "Programming_Reference", "Administration",
   "Installation", etc. It's obviously the next-most-meaningful data in a
   file-name sort. And for the record: KILL book titles that use
   possessives! It's not a "Programmer's Reference" it's a "Programming
   Reference", dagnabbit!! There's no good/obvious character substitution
   for an apostrophe in that instance and, thus, no way to follow the rule
   in the first bullet above.

      (OPTIONAL: You could include 'stage numbers' before the manual
   title, if you want the sort to be even more logical in terms of 'when
   you use the doc'; e.g., "01_Installation", "02_Configuration",
   "03_Programming", "04_Operation", etc.)

   * Part Number because some folks think that way AND to enhance
   searching within a PLM system or on a web site, generally. NOTE that a
   new title should ALWAYS require a new part number, so if the VRM
   changes, it's a new PN and, thus, a newly unique, full file name.

      DO NOT just put new VRM/builds into a new Rev!!! There lies madness,
   as you must correlate VRM to Rev somewhere else outside of the handy
   file list/index/search!!!

   * Revision number for the obvious reasons: no one should be pulling
   down-rev files; no down-rev files should be hosted. (This is also why I
   put the DO NOT in the bullet immediately above: You'd never know which
   down-rev was 'bad' due to corrections versus which are 'good' because
   they actually carry a new VRM's info!!! With this bullet's rule, the
   highest rev is ALWAYS the best/most-correct.)

   * File type extension because of OS handling, obviously.

   Options:

   * Insert additional 'elements' of a file name as required to
   distinguish from other files, ALWAYS from least- to most-specific.

   Caveats:

   * My SOURCE-FILE naming conventions are far more robust, to assist in
   discovery of existing content and, thus, reuse. Those file names ARE
   NOT very 'friendly' and, as such, require some training to both create
   and use for discovery. But in general, they follow the least- to
   most-specific pattern, often using common abbreviations (e.g., "Mgmt",
   "Inst") or 'codes' (e.g., "DIAG" = the file is a screen capture of a
   dialog box; "BTN" = just an image of a button).

   * But I still ALWAYS insist upon the first bullet in "Reasons" above.
   Been burned too often to use 'natural' spacing or (*shudder*) any
   punctuation at all.

   Hope this gets you closer;

   David

   -------- Original Message --------
   From: "Monique Semp" <[1]monique -dot- semp -at- earthlink -dot- net>
   Date: Wed, October 28, 2015 1:17 pm
   Hello, WR-L-ers,
   What are people's thoughts about including a software release number in
   the PDF filename?
   I've been requested to do so, and am somewhat resistant to it. But from
   the Sales team's point of view, it would make it easier for them to
   send out the correct docs to prospects. (Apparently thereaEUR(TM)s a
   history of sending docs from previous releases.)
   But if we indicate the software version in the filename, I'd want to
   indicate the doc revision too. (Sometimes the docs get revised between
   releases, so two doc sets per a given release number.) And then where
   does it stop?!
   Are there any aEURoestandard best practicesaEUR?

References

   1. mailto:monique -dot- semp -at- earthlink -dot- net
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com

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

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives