Skip to main content

Choose the Appropriate Branching Method

There are several ways to create branches of your content in Paligo. Depending on your needs, you can branch a publication, a fork of a publication, or a topic. But how do you know what method of branching is going to best suit your requirements? Here, we explain what you need to consider for each type of branching.

When to Branch a Publication

Create a branch of a publication if you want a new version of an entire publication. When you create the branch, you have the option to branch only the publication or the publication and all of its topics.

  • Branch of publication only

    The branch version will reference the same topics as the original. Changes to those topics will affect the original publication and the branch publication.

    Some common reasons to use this branching method are:

    • You need to work on updating the content for the next release but also keep the original publication.

    • You need documentation for a new product or model that shares a lot of functionality with a previous product.

    In both cases, you have the original publication available for publishing at any time and a branch publication for working on updates. For changes that will apply to both publications, you can update the topic without branching it. For changes that should only apply to the branched publication, you will need to branch the relevant topic and then make the changes in the branched topic. You can also add new topics to the branch of the publication as required. This allows maximum content reuse with the existing topics.

  • Branch of publication and its topics

    Paligo will create a branch of the publication and set it to reference branched versions of all the topics. This can be useful if you want each branch to be a completely separate version. But it can also mean you duplicate content that could be reused. For example, if you have a topic that should be the same in both versions of the publication, it is more efficient to reuse the same topic rather than create multiple branches of it.

    This method of branching is useful when:

    • You need to be able to translate your content into other languages as and when your product is sold in new markets.

      In this scenario, you make a new branch of the publication and topics and you "freeze" them in the In Translation state. These can then be used for new translations. While this is happening, you can continue updating the original publication and topics.

    • Your company is developing a new product that is similar to an existing product but will be developed separately.

      For example, if a subsidiary company is going to develop a new product based on a product from the parent company. They can branch the product's existing documentation and then work on it completely separate to the original documentation. This can be useful if the parent company and subsidiary are working in the same Paligo instance, but intend for the subsidiary to have their own Paligo instance in the future.

To learn how to create publication branches, see Create a Publication Branch.

Note

You can also create branches of subpublications (publications that are nested inside other publications). For instructions, see ???.

When to Branch a Topic

Create a branch of a topic if you want a new version of a topic that is not associated with any publication. This can be useful when you need to update a topic, but still need to publish your publication in the meantime. You can work on the branch of the topic while the publication will continue to use the original version.

When branching a topic, the important thing to understand is that it is separate from your publications. To get the topic into a publication, you will need to either:

  • Add the topic branch to a publication manually

  • Merge the topic branch into an earlier branch (or the original version) that is already added to a publication.

For instructions, see Create a Topic Branch.

If you want to create a branch of a topic that will be included in a publication automatically, see Create a Topic Branch from a Fork .

Note

You can also branch informal topics. These work in a similar way to regular topics: they are not associated with any publications or topics that contain the original version of the informal topic. You can use them independently or you can merge them back into an earlier version.

For instructions, see Create an Informal Topic Branch.

When to Branch a Fork

Create a branch of a fork in a publication when you want to do both of these at once:

  • Branch a topic

  • Update the publication to use the branched version of the topic instead of the original version.

Before you branch a fork, think about what you need to publish:

  • If you only want to publish the publication with a branched version of a topic in place, create the topic branch from its fork. This is quicker than branching the topic separately and then manually adding it to the publication structure.

  • If you might still need to publish the publication with the existing version of the topic in place, don't branch from the fork. Instead, branch from the topic. That way, you can still publish the publication in its current form. You can work on updating the branched topic separately from the publication. When your branched topic is ready to publish, either add it to the publication structure or merge it into the existing topic, depending on your needs.

For instructions, see Create a Topic Branch from a Fork.