One part of the agenda for our day long “Author-it day” was to consider how we would handle multiple streams (versions) of documentation.
As well as major versions of the documents (3.x) that continue to move forward, we also keep up with changes to maintenance releases (3.x.x). The overhead isn’t too bad, we rarely have to make changes for a maintenance release, but we do need to have the capability to do so and this is where we hit a stumbling block.
Author-it offers the ability to version an object (a book or topic for example). You can have multiple versions of an object but only one can be active. So, originally, our thinking was to create the first (in Author-it) version of each Book and then use the basic “1-up” versioning provided by Author-it.
However, when running through a quick demo of such a system, it became apparent that whilst that model works for major releases (X.x) when you consider the occasional maintenance release (X.x.x) then, very soon, your folders become cluttered with a myriad of versions of objects, none of which are easily identifiable to a particular product version.
So, our solution will be to duplicate objects (copy) to a new version specific folder.
We are switching to Author-it just in time for a new major version of the product line. This allows us to import ALL our existing content as 3.0. From that point onwards each major version will kick off with the duplication of all the Book objects (remember, a book is just a collation of topics for output). Then any topics that change, or are added, for that version will be duplicated (copied) and moved to the new version folder.
Clunky? A little. Manual? Completely. But it’s the only way we can manage our versioning process without ending up with a mess of versioned objects.
Unless, of course, we’ve missed something very obvious.
Check out variants in AIT…I think it will solve many of these issues. A variant uses an existing topic, so it’s sorta like duplicating, but it can be edited separately and you can take advantage of embedded topics. Variants are always attached to their “parent”, like versions, and were basically designed for dot releases and the like.
Ahhh yes. Not looked at these yet but have an action to do so (in other words, we did miss something obvious!).
Having looked into Variants today I can quite happily state that, yes, we missed something obvious!
Hi Gordon
You might want to check out this document I wrote that describes one way of handling multi-version documentation – http://hamishblunck.com/index.php/author-it/author-it-tips-and-tricks/27-using-author-it-variants-for-multi-release-software-documentation.
Hamish
Thanks Hamish, I have, since posting this last year, found your document, it is invaluable!