Exploring the Documentation Multiverse through Branching

The multiverse has become a captivating topic in recent years, with insane adventures depicted in the Oscar-winning movie ‘Everything Everywhere All At Once,‘ challenging battles fought by Doctor Strange, and different characters embracing the role of the well-known hero Spiderman, among other examples from popular culture. But what if I told you that the tech writing industry was already exploring these narrative dimensions long before it became a popular concept?

For technical writers, it’s important to maintain a continuous life cycle of their technical documentation. This gives them an insight into past revisions and lets them closely track all the changes. Each important update in a life cycle of a certain guide results in a release (minor or major). Paligo can preserve releases in two forms:

1. Fully editable – necessary if you need to make multiple versions of the same guide available simultaneously or if you expect any updates to old versions.
2. Uneditable – if you don’t need to further modify any of the released versions. You keep them only for archiving purposes and to be able to compare the changes over time. As you can guess, releases like that weigh less and don’t result in excessive files cluttering your folders. You won’t need to edit them anyway, right?

Let’s concentrate on the latter. We call releases like that snapshots. They’re like photos of significant moments: It’s me when I was sixteen. It’s me on my graduation day. It’s me on my wedding day, etc. Similar to photos, they’re not really editable. You can always recreate (restore) content from them, but their main purpose is to mark an important milestone in your document life cycle.

How does the concept of the multiverse fit into all of that? Bear with me, as the definitions I’ve introduced above are a necessary foundation for a further understanding.

Comparing snapshots is akin to nostalgically reflecting on your old photos and a hairstyle from years ago that has long since gone out of fashion. With snapshots, you can also easily publish a PDF highlighting the additions and removals between two releases. The concept of snapshots can be illustrated in a very simple way:

But what if you were to take a step back to high school and choose a different university or career path? Have you ever imagined yourself as a dancer or an astronaut? This is where branching comes into play. It allows us to preserve a release in a fully editable form and let it live its own parallel life. Yay, we’ve finally referred to the concept of the multiverse!

Let me continue with a quote from my wiser colleagues on the innovative Documentation Team:

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 that acts like a copy, but Paligo understands it is related to the original version.

It means that whenever you author, review, and approve a certain version, you can extract from the main branch to preserve it in an editable form. Extracting released versions this way offers numerous advantages:

• New branches are not isolated. If you introduce any changes, they can be either specific to each branch or you can merge them between branches to include them in other versions too.
• You can keep updating and continuously maintain old versions of your docs without influencing newer versions.
• You can publish older versions of your content at any time to your preferred destination, depending on your choice.
• You can give your end-users simultaneous access to multiple versions of the same guide.

We could illustrate that in the following way:

Each dot represents a snapshot (important milestone on a given branch). Each arrow represents a branch (alternative version of the main document preserved in an editable form).

While the branching feature allows you to keep different versions in separation, remember that it’s best to sunset old versions once they’re no longer needed. After all, we don’t want to hoard old content and get stuck under the avalanche of components from bygone times, right? And if you need to keep old versions for a couple of more years, you can also export them from Paligo and store them on a dedicated drive.

But is the purpose of branching limited to this use case? Absolutely not!

Actually, what I’ve described above is not necessarily the most popular use case for branching. Typically, especially in the era of the SaaS business model, organizations don’t need to maintain multiple versions of their documentation; they often present their customers with only the latest one. While the previous section might be more relatable to anyone documenting hardware or on-prem applications, this one is going to be interesting for a broader audience.

When you need to initiate significant modifications for an upcoming release without disrupting the existing version, consider creating a temporary branch. This lets you work on changes or updates independently, and when the time comes, seamlessly merge them into the main branch with the updated content. In this workflow, create a temporary branch for your publication and the sections that need updating. This allows you to work in a safe environment without affecting the main branch, which can still be republished at any time. Once changes are complete and fully reviewed, you can merge them into the main branch.

More often than not, the main branch should always be ready for publication. This means only reviewed, approved, and released content should reside there. It allows you to publish on demand whenever there’s a need for an urgent hotfix, without publishing someone’s work in progress.

Furthermore, if other writers need to start documenting features for release on a different day, they can begin working in their own temporary branches. This way, everyone can work on necessary updates in parallel without interrupting each other. When merging temporary branches into the main one, there’s an option to automatically delete the merging branch that you don’t need anymore, meeting a fate reminiscent of universes that collapsed due to the reckless actions of superheroes meddling with the space-time continuum.

Each dot represents a snapshot (a saved, uneditable release). The pink arrow represents the main branch (editable version of your content). Each gray arrow represents a temporary branch that’s later merged into the main branch.

Typically, if your content has different variants depending on specific conditions, you’d use filter attributes, taxonomy filters. You could also use variables if there are apparent variants of different phrases, values or images. These functionalities allow you to conditionalize the same content and make it suitable for different audiences, specific customers, markets, output formats, etc. Usually, there’s no need to create a branch, as all those variants can be captured within the same branch. However, there are cases where the extent of differences is so huge that filter attributes are no longer the most efficient way of managing content variants. Guess what? Branching can also save you here! It allows you to work on a highly modified version of your documentation that’s still connected to its main flow.

Another variant of that use case would be if you’d like to ensure that some parts of your documentation are not translated into a specific language to avoid excessive translation costs. One idea to avoid that would be to create an alternative branch, remove everything that’s not supported in a given market, and send only that for translation. However, remember to stay cautious, as sometimes the additional effort related to managing alternative translation branches might exceed the cost of excessive translation, so it’s worth balancing the needs carefully first.

Paligo offers sandbox instances for all Enterprise customers. You can freely conduct limitless experiments in this environment. However, there may be times when you’d prefer more direct access to your real-life content. For that purpose, you’re free to use branching. This allows you to run as many tests as you need and perform test publishing jobs, observing how your changes affect the final outcome.

Feel free to do that! You can combine different use cases such as:

• Creating snapshots for marking important milestones in your document lifecycle.
• Creating branches for different releases to preserve them in an editable form.
• Introducing changes by working with temporary branches.
• Using branches to create highly specific versions of your docs.
• Employing branching for testing purposes.However, I recommend not doing so until you thoroughly analyze your internal processes and confirm the applicability and necessity of each use case. Remember, a proper workflow should be considered first to avoid excessive files and steps. As you know, there are alternatives available for different features, and there’s no one correct approach to content versioning.

I’m absolutely not suggesting that branching is a cure for everything! It should be used with caution. Overusing it can cause unnecessary clutter in your content repository, and merging recklessly can result in some additional efforts (though they can be reverted). However, proceed carefully when creating these alternative universes, and I’m confident you’ll unlock the full, boundless potential of your documentation.