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:Robert Lauriston <robert -at- lauriston -dot- com> To:TechWR-L <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 28 Oct 2015 18:36:57 +0100
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
