Focus On: Versioning

It’s time to move on to the next part of our Component Content Management System (CCMS) interview series: versioning. Roger Gelwicks will cover his helpful tutorial in greater depth during this interview, focusing particularly on ‌version control to help you gain a better understanding of versioning and how it can be used to keep track of changes to a document.

Roger Gelwicks: When we discuss versioning, it’s really a matter of every single revision in Paligo being saved, so that you can always go back to it. And that applies to almost every element in Paligo. An entire publication could be versioned. The same goes for topics. Even individual elements, like paragraphs, can have their own revisions, which is really helpful. That way, it really gives you more granular control over your changes to your content over time.

Every time you make a change to something in Paligo, there’s a date and a time to when that is done. There’s a user’s name that’s assigned to it, so you know they were the one responsible for that revision. And so, if you have that revision history in place, it means you can’t accidentally over-save. You can always go back to a previous revision or version of almost anything. So that’s‌ the main idea behind it.

We can compare that to something like Microsoft Word, which doesn’t really have a versioning component. If you want to save a new version of a document, you just have to use the ‘Save As’ feature. But every time you save something in Paligo, that revision is saved, and there’s always a list of the revisions that you can reference at any time. So that makes it a lot easier to manage your content when you can always go back to the previous version and do what you need to do.

Roger: Exactly, and I think the biggest benefit is that it’s just more granular. If you remember that you had a paragraph that changed a while back, you can‌ look back at the history for just that one paragraph element and see exactly what happened and who did the change. That is really helpful if you’re trying to reverse-engineer your documentation. If you need to ask, ‘How did we get here?’ And that helps you plan your future projects.

Roger: Branching is a pretty powerful feature in Paligo. It can be very complicated, and it’s definitely something you only want to do when you really know what you’re doing, but branching can be a very powerful technique to maintain multiple versions of topics or publications.

When I was a Paligo customer, I would use branching as a great work-in-progress technique. If I had a topic that I was working on, and I just wanted to try out some significant changes before I committed to them, I could create a branch of that topic and make all the changes I wanted for that topic at will. And then, when I had the branched topic the way that I wanted it, I could decide then to merge that branch with the original topic and then make it one topic again. So it’s a way to do some experimenting on a topic without fully committing to those being a version.

As I mentioned before, you can always make any changes you want to any topic, and you can always go back. But sometimes it’s easier if you can‌ play around in a branch, see if you like it, and then when you’re ready to commit to the change, just merge it.

The other thing that’s helpful about that technique is that it helps you stay organized. Maybe a product was improved and you need to update a whole user manual for that product. It can be easier to track which things‌ need to be worked on if there’s an open branch for just individual topics as opposed to seeing all these topics and being unsure which ones need to be worked on. With branching, you can make the changes and then just merge them when you’re done. And it’s a good way to‌ track your progress with a massive docs update.

The other thing with branching that can be helpful, is that you don’t actually have to merge them. Sometimes it can be helpful to have a branch for a topic, and then just maintain the two branches indefinitely. It could be helpful for them to have a relationship, being branches, but they’re still technically independent topics. And of course, you can move branches around to different publications.

We’ve got a great feature in Paligo where you can label a branch, so you know what each branch is for. Not to mention, you can have branches of branches. You could get pretty sophisticated with this if you wanted to.

Depending on your use case and depending on how complicated your documentation is, branching can either be something you make great use of, with some complicated structures, or you may not use it at all, because it might overcomplicate your workflow. But it’s a very powerful way to take versioning to the next level and help you really manage your content.

Roger: Yeah, I would say it’s best to keep the label pretty simple. The other thing I would say is to make sure your label has at least three characters, because if it’s three or more characters, you can search for them more easily. With Paligo’s advanced search functionality, as long as something has three or more characters, it can be searched. As long as it’s a naming convention, everybody understands, that’s the main goal. If you’re using a lot of acronyms and only one or two people on the team know what those mean, then that’s a problem. You want to make sure it’s something that your whole team can understand.

Roger: What I’m about to say is more encouragement than advice. Paligo really empowers you to try things out with your content. I think sometimes when you approach a new application, like a new authoring tool, or a new way to work with your content, sometimes you can feel held back because you don’t want to break or change something permanently. As long as you take care to only delete content you don’t need anymore, (and even then, you can often restore deleted content), you can do whatever you need to do. There’s always a way to go back. So, you should definitely feel empowered to experiment with your content and take advantage of versioning, knowing that every time you make a change, it’s going to be saved as a revision.

Another thing is that versioning works really well with the ‘Work in Progress’ status feature. So anytime you move a publication from ‘Work in Progress’ to ‘Released’, that also gives you the opportunity to give it a version name and you can mark it as a major or a minor revision with the internal numbering convention in Paligo to help you track that information. As long as you’re using all of these tools available to you, you should have confidence when you’re editing, because you know you can always go back to previous versions. Plus, it’s also really easy to create additional content from these revisions.

Like I said before, every single topic has its own revision history. You can even create a brand new topic from a previous revision of a topic. So, if you remember that a month ago there was a topic that was focused more on one particular subject matter but it’s changed over time, you might decide to create a new topic based on the way it was before. You can easily do that with just a few clicks. There’s no need to recreate everything from scratch, because it’s all tracked from the beginning. Versioning is really easy to do as long as you’re taking advantage of all the tools.