RE: PDF filenames - include release designation ?

Subject: RE: PDF filenames - include release designation ?
From: "David Artman" <david -at- davidartman -dot- com>
To: "Monique Semp" <monique -dot- semp -at- earthlink -dot- net>, "TechWR-L" <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Fri, 20 Nov 2015 13:31:58 -0700

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


Previous by Author: Re: Knowledge Base Software Tools
Next by Author: RE: FM (2015) - copy/paste and keep tracked changes ?
Previous by Thread: Re: "makefiles" vs. "Makefiles" vs. "make files"
Next by Thread: any visual Track Text Edit status - in FM 2015 ?


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


Sponsored Ads