Creating and Maintaining Documentation for Multiple/Concurrent Revisions of Software

Many companies (particularly those in software development) are faced with supporting multiple releases of a product - where you must write and manage the documentation for the various releases concurrently. For example, let's say you're a software company. You release Version 6.1 of your product. You then release Version 6.2 and subsequently Version 6.3... and the cycle continues. All - or some - of the releases are still in production, and as such you are still required to maintain and update the documentation for each release. A change to the documentation for the current version, may also need to be made to the documentation for the earlier version.

Author-it's version control is not the ideal solution, as only one version of an object can be active at any one time.

You could use the Localization Manager to maintain concurrent product versions, keeping the current version as the source library, and creating a new localization for each version/release. You could then push out updates to previous version as and when required, and/or continue to maintain each version (Target Library) independently. However this approach is not really ideal either. Apart from the licensing requirements, the Localization Manager works best when everything in a library needs a variant - as happens with languages and some other applications. This is not generally the case with software releases.

To manage concurrent releases within Author-it, each release must have its own Book. Each Book should share the common objects relevant to all releases, as well as containing those that are unique to its release. The best (and easiest) approach is using Author-it's Duplicate function to create a copy of the original Book, then make the necessary modifications to the copy.

To Duplicate a Book and Add or Reuse the Relevant Topics:

In this example, we'll refer to the initial release as R1, and the new release as R2.

1. Open the R1 Book, then choose Object > Duplicate from the Author-it main menu. Another Book is created called "Copy of..."
2. Rename the new Book for R2 as appropriate.
3. Remember that because exactly the same topics are used in both Books, any changes you make to a Topic will occur in both Books. For topics that need to change in the new release you have two choices.
   1. If the topic just needs extending, then you can create a new topic, embed the R1 topic in it and add the additional content before or after it.
   2. If the content needs more extensive change and the changes only applies to R2 then duplicate the R1 topic and make the changes to the new topic.
4. Remove the old R1 topic from the R2 book and include the new R2 topic.
5. Add any new topics that only apply to the new Book, including any that you have just duplicated and changed. Remove any topics that you do not want from your new Book's Contents list.

   Note: Any graphics affected would also require duplicating, as would hyperlinks and index entries.

Using this process you only create duplicate objects for those that actually require it. This also makes translation much easier and helps reduce other work (such as reviews).

By using release states and folder security, you can ensure that changes to topics that span many releases of the software are properly controlled. A strict process should be followed to ensure people don't change objects inadvertently when those changes could affect multiple releases. It's also a good idea to use a folder structure that keeps objects common to all releases in one area, and object specific to individual releases in separate areas.