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.
Subject:Re: PDF filenames - include release designation ? From:Ryan Young <ryangyoung -at- gmail -dot- com> To:Robert Lauriston <robert -at- lauriston -dot- com> Date:Wed, 28 Oct 2015 12:18:58 -0700
What Robert said.
Doc revisions that occur between releases shouldn't change the version of
software that is being documented, unless the revision is part of a hotfix,
in which case the software version should also be incremented.
On Wed, Oct 28, 2015 at 10:36 AM, Robert Lauriston <robert -at- lauriston -dot- com>
> That seems essential to me when various customers are using various
> releases. Otherwise it's easy for people to get confused by consulting
> the wrong version of the docs. (If everyone is always on the current
> release, as is typical with SaaS apps, the issues are different.)
> In my last job I used FrameMaker and would rename the book file for
> each release.
> Generated files usually don't belong in source control.
> On Wed, Oct 28, 2015 at 6:17 PM, Monique Semp
> <monique -dot- semp -at- earthlink -dot- net> wrote:
> > 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 thereâ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 âstandard best practicesâ?
> > (I have to admit the my reluctance is for reasons that arenât actually
> applicable in the given situation. For example, in repositories, you lose
> the ability to track changes and updates if you change a filename. But if I
> go with a structure in the git repo for the FrameMaker files (which are
> binary and so not amenable to diffs anyway) where I manually create new
> folders/directories for every release, git tracking wouldnât really be
> applicable. And if I instead just branch for every release, which is what
> Iâve been leaning toward, it doesnât matter either if the deliverable PDF
> filenames, which are generally copies of the default filename inherited
> from the FrameMaker .book file, are different in every git branch.)
> > As well, non-dynamic PDF filenames would be important if we were using a
> doc portal where we could send automated messages upon file updates. But
> thatâs not applicable.
> Visit TechWhirl for the latest on content technology, content strategy and
> content development | http://techwhirl.com
> You are currently subscribed to TECHWR-L as ryangyoung -at- gmail -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
> 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
Visit TechWhirl for the latest on content technology, content strategy and content development | http://techwhirl.com