Basic question: Book revision best practices

[Syed Zaeem Hosain (Syed.Hosain@aeris.net)]

Yes! I totally agree with using variables for version numbers, release dates, and the like, inside the documents – I was going to mention this too, but forgot!

Similarly, NONE of the files have version numbers “encoded” in their file names.

But, since the files and book for each version are in separate folders, I DON’T have to put the version number in the file name of the book either. If needed, I simply rename the output PDF filename if I want to have the version number in the name.

BTW, using variables works beautifully to update ALL locations where any bit of information needs to be correct, and easily updated for the next version, etc.

And, in some specifications, I use variables for critical stuff that MUST be “consistent” throughout the document. So, while some of my simpler documents have only a few variables, there are others (not long docs either!) that have near 800 to 1000 variables.

As a direct result, the ability to manage variables at the book level using BookVars from Leximation (thank you, Scott Prentice!) is absolutely essential to me. This is my most-oft-used add-on to FrameMaker and heartily endorsed!

Z

From: framers-bounces at lists.frameusers.com [mailto:framers-bounces at lists.frameusers.com] On Behalf Of David Artman
Sent: Thursday, February 05, 2015 1:44 PM
To: Tim Pann; framers at lists.frameusers.com
Subject: RE: Basic question: Book revision best practices

HUGE subject, but I'll just note one element:

>> Now I want to make changes, so it will become version 1.1. What do best practices say to do? I assume save all content, TOC, and title files as new "v1-1" files. Should I create a new "v1-1" book file into which the v1-1 content goes? Or should the book file itself be version agnostic?

I'd recommend eactly the opposite:
* Do NOT use any version-specific text in FM file names.
* DO use version-specific names in the BOOK files (as that's what the PDF will eventually be called; and renaming a PDF post-generation breaks inter-document links). Just make a copy of the previous BOOK file, rename it to the next version, and archive the old BOOK file (or not, whatever).
* Control ALL references to version in FM files with variables, that you can easily change them BOOK-wide with Import Formats (Variables only).
* OPTIONAL: Use Conditions to maintain version-specific changes: "Deprecated" and "New" are sufficient for most stuff and allow for highlighting changes in review; and if you need to note when/why, add a "Release" Condition in which you note (e.g., "[Removed in v1.1 per John Doe]" or "[Workaround no longer needed; fixed in v1.1]).
A more-complex Conditional version-tracking would require you to manage a lot more (i.e., you could end up with a nightmare of overlapping conditionality for persistent features with minor tweaks each release). If you are already doing something to archive (ZIP up and stow away, even) each version's full set of working files, it's trivial to roll back, and you do not reeally need such 'always-visible' deltas fwith a single, canonical set of working files.

Again, HUGE subject, and I onl touched on the simplest method of maintining version history and simplify review for your SMEs.

HTH;
David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.frameusers.com/pipermail/framers-frameusers.com/attachments/20150205/20547aa2/attachment.htm>