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.
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.
When you create a branch in Paligo, the result varies, depending on:
-
The type of content you branch
-
The branching options you choose
-
Where the branch is created. Branching a topic from the Content Manager is different from branching a topic from the Structure View.
In the following sections, we explain what happens when you create a branch. We also explain how Paligo handles content reuse, cross-references, and images for branched content.
You can Create a Publication Branch. When you do this, Paligo will:
-
Create a branch of the publication
-
Let you choose how you want reused publications to be handled.
With automatic branch creation, Paligo will create branched versions of any reused publications, but only for those at the top-level of the original publication. If there are reused publications that also contain lower-level reused publications, those lower-level ones will not be branched automatically.
If you do not use automatic branching, your branched publication will use the original versions of any reused publications (sub-publications).
-
Let you choose how you want reused topics to be handled.
If you choose to use automatic branching, Paligo will create a branched version of every topic in the publication. Any changes you make in the branched topics will not affect any other branches or publications.
If you do not use the automatic branching, Paligo will create a branch of the publication only, not its topics. The branched publication will reuse the original versions of the topics.
Note
Auto-branching of topics is designed for particular scenarios, and in most cases, we recommend that you leave it disabled (clear checkbox). This is because auto-branching can result in unnecessary branches of topics where reused topics would be more appropriate.
If you Create a Topic Branch from a Fork for a topic, Paligo will:
-
Create a branch of the topic
-
Set the publication fork to link to the branched version of the topic instead of the original version of the topic.
-
Check the original topic for reused text fragments. These text fragments will also be reused in the branched version of the topic, so the IDs will be the same. If you change them in the branched version, those changes will also apply in all of the other topics where those text fragments are used.
-
Check the original topic for text fragments that are not reused. These are "regular" paragraphs and content structures and Paligo will give these new IDs in the branched version. So if you change them in the branched version, your changes will not affect the original branch.
-
Check the original topic for any reused components, such as topics inserted inside other topics. These components will also be reused in the branched version and so do not get new ids.
-
Check the original topic for references to other files, such as images. The branched version will use the same files as the original version. Paligo will not create a new, separate file. For example, if the original topic contains an image, the branched version will contain the same image (they both reference the same image file in the Media library). If you edit the image, those changes will apply wherever that image is used.
If you Create a Topic Branch in the Content Manager (rather than from a fork in the publication structure), Paligo will:
-
Create a branch of the topic
The branch is a stand-alone branch and is not used in any publications. Any publications that use the topic will continue to use the original version.
-
Check the original topic for reused text fragments. These text fragments will also be reused in the branched version of the topic, so the IDs will be the same. If you change them in the branched version, those changes will also apply in all of the other topics where those text fragments are used.
-
Check the original topic for text fragments that are not reused. These are "regular" paragraphs and content structures and Paligo will give these new IDs in the branched version. So if you change them in the branched version, your changes will not affect the original branch.
-
Check the original topic for any reused components, such as topics inserted inside other topics. These components will also be reused in the branched version and so do not get new ids.
-
Check the original topic for any reused components, such as topics inserted inside other topics. These components will also be reused in the branched version and so do not get new ids.
-
Check the original topic for references to other files, such as images. The branched version will use the same files as the original version. Paligo will not create a new, separate file. For example, if the original topic contains an image, the branched version will contain the same image (they both reference the same image file in the Media library). If you edit the image, those changes will apply wherever that image is used.
If you create branches of publications and topics that contain reused content, Paligo will handle the branching like this:
-
Text fragments
Paligo will check the original topic for any text fragments that are reused. These text fragments will also be reused in the branched version of the topic, so the ids will be the same. If you change them in the branched version, those changes will also apply in all of the other topics where those text fragments are used.
In the branched version, Paligo will only give new ids to those text fragments that were not reused in the original version.
-
Components
Paligo will check the original topic for any reused components, such as a topic that has been inserted into another topic. These components will also be reused in the branched version. If you change them in the branched version, those changes will also apply in all of the other topics where those components are used.
-
Reused publications inside a publication
You can create a branch of a "parent" publication and set Paligo to branch its "child" sub-publications automatically.
For example, if you have a "Documentation" publication that contains "Getting Started" as a sub-publication, you could branch "Documentation" and set Paligo to automatically branch the "Getting Started" sub-publication too. The resulting "Documentation" branch would contain the branched version of the "Getting Started" sub-publication.
For more details, see Create a Publication Branch .
If you need to insert a cross-reference to a branch, you should usually target the original version of the topic and not the branch. When you publish, Paligo understands that the cross-reference should go to the version of the topic that exists in the publication.
With publications that contain multiple versions of the same topic or branch, you should make sure cross-references target the appropriate fork.
For more details, see Add a Cross-Reference to a Branch.
When you create branches, Paligo checks to see if the original version of the topic contains images. If it does, Paligo will keep the same references to the image file in the branched version. Paligo will not create a branched version of the image file.
If you edit an image, those changes will apply wherever that image is used, and that includes other branches.
If you want a branched version of a topic to use a different image, add the new image to the media library and insert it in the branched topic.
To learn how to add images, see Add an Image.
Merging is the process of combining one version of a branch with an earlier version. When you merge, you have the choice to merge everything or you can compare the differences between the branches and choose which parts you want to merge.
For example, let's say you have a topic about "Temperature Sensors" and you branch it into two different topics. You now have the original "Temperature Sensors" topic and a branched version of it. These branches are completely separate, and you now have the choice to:
-
Let the multiple branches exist concurrently in Paligo as separate, but related, topics
-
Merge the branches into a single topic
-
Merge parts of the branches. The branches will still exist concurrently as separate topics, but some of their content will be merged so that it is identical in all versions. You can choose which parts you want to merge and which parts you want to remain separate.
Paligo's Merge document dialog. Use it to merge all differences or choose specific differences to merge.
The process for managing merges is slightly different depending on whether you want to Merge a Topic Branch or Merge a Publication Branch.
Note
Merging branches will not affect any mapping you have in place for publishing to other systems, such as Zendesk and Salesforce. To find out how Paligo manages the ids of the content, see What Happens When You Merge a Branch?.
When you merge a branched publication or branched topic, Paligo moves changes made in one branch into another version of the content. For example, if you choose to merge a branch with the source version, Paligo will place content from the branch inside the source.
You choose which parts of the content will be updated, added, or removed when you set up the merge process (see What is Merging?. Paligo has a merge dialog where you can see what is going into the publication/topic that receives the merge content.
The dialog shows the different versions and a preview of the end result:
-
The "merge from" branch contains the content that is being used to update the "merge to" branch
-
The "merge to" branch receives the changes made during the merge.
If the merge adds a new element, such as a paragraph, to the "merge to" version, the new element uses its id from the "merge from" version. So the "merge to" content gets a new element with a new ID.
If the merge updates an existing element in the "merge to" version, the content keeps its original ID. The id from the "merge from" is ignored. This applies to the publication id and topic ids as well as the individual components for paragraphs, lists etc.
Note
As Paligo keeps the original ID for content that already exists, it means merging will not disrupt any mapping you have in place for publishing to support systems, such as Zendesk Integration and Salesforce Knowledge Integration.
Comments
0 comments
Article is closed for comments.