Version Branching

Branches are concurrent/parallel versions of content. It means you can create a separate parallel branch/fork of your content, a Publication or a topic, that can live side by side with the original.

It is similar to a copy, but with more features. A branch "knows" that it originates from another version, and if needed, you can later merge the content of the two different versions.

Some typical use cases for creating branches are:

  • You are working on a version for a specific product, and it is still in development, being updated, etc. But then the next release of the product is due, and you need to start working on the documentation for that version.

  • You are considering some major changes to the documentation and its structure, and you want to experiment before abandoning the old version, or similarly:

  • You are working on a major change for the documentation that will take some time, but the development team is making many small continuous updates that require updates in the live documentation. So you need to be able to publish intermittently until the major overhaul of the documentation is done.

  • You may have two different versions that need to live concurrently, but some changes should be easily implemented in both.

  • You need to send a project to translation, but you still need to keep working on further developments meanwhile.

  • And so on.

Caution

Branching can be very powerful, if used for the right reasons, and with care. But it can also cause complications if used carelessly. In many cases other techniques can achieve the same results, but with greater simplicity and reuse opportunities.

Even when branching is the best choice, it is still important not to create overly complex scenarios.

Note

There are two different configurations available for branching:

  • In the Simplified branching, you can only have one main branch. All branches must be created from that same branch. Use this if you want to keep the branching simple, and have no need for concurrent versions, but only branches that live temporarily.

  • In the Consecutive branching, you can create a new branch from any branch, even from other "secondary branches" (i.e branches that were once branched off another topic or publication). This works best if you also plan to use branching for managing consecutive versions that will live in parallel.

    With this type of branching, the numbering of branches will look slightly different, with a consecutive numbering of the branches, but with the origin branch in parentheses:

    branchnumbering.png

You should decide which configuration to use and set this in System Settings.

Publication branches and topic branches

You can create a branch from either a publication (or "project") or a topic. They are similar, but with some differences:

  • A publication branch creates another version of the publication, but not the topics inside it. A branched publication will reuse the same topics as the origin branch (the "main" branch). So if you branch a publication, and then make changes to the topics in the branch, those changes will also affect the topics in the origin branch. But you can add, move, and remove topics from a branched publication without affecting other branches.

    To change a topic in one publication branch, but not the other, create a topic branch.

  • A topic branch is a copy of the original topic. If you make changes to a topic branch, those changes do not affect the origin topic.

Note

If you branch a topic that contains reused components, only the topic itself is branched. Any reused components inside the topic are not branched, and so if you change them, the changes will apply wherever those components are used. For example, let's say you have an "Introduction" topic that contains a "Prerequisites" topic as a component. If you branch the "Introduction" topic, the "Prerequisites" topic inside it is still the original version. You need to branch any reused components separately.