I’ve already mentioned this scenario in the announcement about the brand new Baseline Manager for DITAToo DITA CMS, but want to articulate it again, just to refresh the memories or in case you missed it.

Suppose you need to send a project for translation. However, your company is preparing a new release of the product, so you have to keep working on the project while it’s being translated. There is good chance that by the time you get the translation, the project in the source language will be already several versions ahead. The translated project will reflect a past state of the project and will be unsynchronized with the content in the source language.

Similarly, like some of our customers, you might be in a position when you need to translate a project into several languages, but for the time being, you’ve got a budget only for translation to one or two languages. The translation for the rest of the languages will be done later, but by that time, the project in the original language will evolve.

Or maybe you want to publish a project as it was a few months ago.

A popular solution would be to create a copy of the project and put it aside. You would be working on the original project while the copy would remain frozen. After you got a translation, you would somehow associate it with that copy rather than with the original project. When you want to send the project for an additional translation, you would send the frozen copy rather than the original project which has been already evolved. If you need to publish a project as it was some time ago, you would publish the frozen copy.

This is how your folder structure might look like (at least, initially):

creating_copy

This approach is totally legitimate when you are using a version control tool based on the file system just because you don’t have any other choice. But the drawbacks are quite clear:

  • The structure of your project will become eventually overcomplicated. Just think about it: every time, you need to freeze a project, you will have to create a full copy of it. Then within each copy representing the project in the source language, you will create a separate copy for each language.
  • It will be very easy to begin mistakenly updating a copy instead of the original project. After you realized that you are actually updating the files that were supposed to be frozen, you would have to merge the changes to the “right” project and rollback the changes in the copy.
  • By creating a copy of the project, you will be wasting your disk space and create shadow files that will likely puzzle you later.

This is how your folder structure might look now, and this is just one project with just one frozen copy and just a couple of translations:

copies_with_translation

In the reality, it could be much worse, as you will have multiple projects that use the same topics.

With Baseline Manager, it’s different and much easier.

Think about baselines as version tags. Suppose that you have a project in the middle of its lifecycle. The project consists of a DITA map, various topics, and a number of images. Each topic and each image, as well as the DITA map itself, is currently at its own version number. For example:

  • The DITA map is currently at version 6
  • Topic A is at version 8
  • Topic B was just recently added, so it’s still at version 1
  • Topic C is at version 2

This figure schematically demonstrates the situation:

current_state

Now, let’s say that you want to freeze this particular state so that you’ll be able to get back to it (for whatever reason, not necessarily for translation). Using Baseline Manager, you create a baseline. This operation “tags” each file included into the project (including the DITA map), at its current version, as belonging to this baseline.

From this point on, the project’s lifecycle can continue as usual. You can check files out and back in, version numbers will grow, and everything will go on just like before, just the baseline will be remembered:

creating_baseline

But now, should you ever want to go back to the project state you froze, you can do that at whim. You can download the entire project, and get all the files just the way they were when you created the baseline:

  • The DITA map at version 6
  • Topic A at version 8
  • Topic B at version 1
  • Topic C at version 2

You can also publish the baseline or upload a translation to that baseline. Of course, you can create as many baselines as you need. You ca retrieve any of them at any time:

multiple_baselines

So with baselines, no additional copies which will eventually cause a mess are created. You will never mistakenly update a topic that is supposed to be frozen. And you will never lose track of your project files.

If you still haven’t seen how Baseline Manager for DITAToo DITA CMS works, here you go. Or read more about release management in DITAToo DITA CMS.

Leave a Reply

Your email address will not be published. Required fields are marked *