Skip to main content

Branching

Branching is designed for creating multiple versions of related content. It is similar to copying, but has more features and gives you more options when working with your content.

With a branch, you create a new version of a publication or topic. This new version acts like a copy, but Paligo understands it is related to the original version. So depending on your requirements, you can:

  • Use the original version and the branched version separately as parallel versions

  • Merge the original and the branched version back into a single version at a later time.

For example, in the following image, the "Acme HomeHub User Guide" has been branched. Here, the original (1) and the branched version (2) both exist as separate publications with separate topics. You could continue to use them as separate versions or merge them together to create one publication.

Two publication structures side-by-side. One is numbered 1 and is the original version. The other is numbered 2 and is the branched version.

1 = Original, 2 = Branched version

This is just one way of using branching. You could have branched publications with reused topics or a mix of reused and unique topics too. There are many different possibilities.

Tip

Use branching with care. It is a powerful feature that can help you save time by creating and merging different versions of content. But without careful planning, it can also make your content over-complicated and more difficult to manage. We recommend that you avoid over-complicated branch structures.

Common Use Cases for Branching

If you are unsure about how you might use branching in your organization, here are some common use cases to inspire you.

  • Publish a release, work on the next release 

    You use one branch for publishing the official documentation for the latest product release. You use the other branch to work on updates for the next product release.

  • Two different versions that live concurrently 

    You need to update and publish two similar, but different, publications. For example, if you have user guides for two different models of a product that only have minor variations.

  • Experiment with your content 

    You are considering some major changes to the documentation and its structure. So you create a branch and use the original version for publishing and then experiment with a new structure in the branched version. If the experiment goes well, you can merge the branches later.

  • Work on long-term changes 

    You need to make changes that will take a considerable amount of time to complete, but also need to publish minor updates on a regular basis. You can create a branch for your long-term changes and then either use the original branch or another branch for the quick updates.

  • Work during a translation project 

    You need to send content for translation, but also work on the next version of the content while you are waiting for the translation to be returned. For this, you need to use branching.

Note

Branching is a powerful tool that can save you a lot of time and make it easier to manage multiple versions of your content. But it can also become complex to manage, so we recommend that you only use it if you need it and you should also try to keep your branching as simple as possible. The more complex your branching, the more difficult it will be for people to understand how the content is branched and which branches they should work on.

Getting Started with Branching

To branch your content in Paligo, we recommend that you:

  1. Make sure you understand the basics of branching and merging.

    We explain how branching works in Paligo in these introductory sections:

  2. Set the branching mode for your Paligo instance. We recommend that you enable Consecutive branching mode as it allows for branching from other branches, which gives you more possibilities with branching. But if you have a specific need to only branch from the original branch, you can set Paligo to use Simplified branching mode instead.

    For instructions, see Select Branching Mode.

  3. Decide on what parts of your content need to be branched and choose the appropriate method of branching.

    Paligo has several different methods for branching and they each work differently as they are designed for different scenarios. To find out which method is going to work best for your requirements, see Choose the Appropriate Branching Method.

  4. Create your branches!

    For instructions, see:

  5. If you need to merge a branch back into an earlier branch or the original branch, see Merge a Topic Branch or Merge a Publication Branch.