More often than not, it’s hard to predict what the process of writing documentation will look like.
Software products are in a state of constant change, with new updates needed to keep the product relevant and competitive.
The documentation is no different. With all the changes the product goes through, the documentation also needs to go through different versions to stay relevant.
That’s why document version control is crucial. It grants you the level of control over the documentation and its changes that you need to keep everything on track.
Luckily, in this article, we’ll present you with ways to master document version control and use its many advantages.
Let’s dive in!
Define Naming Conventions
One of the most valuable advantages of document version control is that it allows you to track and manage different iterations of the same document.
However, although that has many benefits for the team and the whole organization, it implies there are many versions of the same document.
That’s why defining clear naming conventions is crucial for successful document version control.
Confusion, time-wasting, and frustration in the team are inevitable if the organization fails to establish the model of naming documents.
For instance, just imagine coming across a folder with a dozen documents named like this:
Naming documents like that is hardly helpful.
Why? Because you can’t tell from the name what the document is about. You would need to open every document to see that, and that certainly isn’t time efficient.
So, what’s a better way to name your documents?
Jake Poinier, freelance writer, editor, and publisher, recommends keeping your document names:
- Descriptive
- Brief
- Consistent
The example of document naming from Twitter that we saw earlier is consistent, but it’s not descriptive, and it could be shorter, too.
Other general recommendations are to indicate a version of a document with a number, as well as if some minor changes were made to the document.
When we bring all of that together, your document names can look something like this:
As you can see, the first part is the file’s name; in this example, it’s “API_overview”.
That part should remain consistent, so every team member knows how to find the document and its versions.
Also, notice that it’s brief and descriptive, so we’ve applied all three of Poinier’s naming recommendations.
The second part is the file version, or “v2”, in our example.
Whether you use “v2”, “v02”, or just a number, it’s up to your preference, but you should be consistent when you choose one convention.
You can use the third part of a document name if there is a minor change to the document that you and your team assessed isn’t enough to justify creating a separate version.
That can be fixing typos, changing the font or formatting, etc.
That is just one example of a naming convention you can use. The crucial part is to define how you and your team will name your documents and stick with it.
By doing that, version control will be much easier, take less time, and you’ll achieve a better workflow.
Maintain a Clear Document History
How many times did you wish you could roll back time and learn why something went wrong and when, so that you could fix it?
We all did, whether it was a lunch that burned on the stove, a relationship, or—software documentation.
And while document version control can’t help you with the first two scenarios, it certainly can with managing documentation.
A significant part of that is maintaining a clear document history.
What does that precisely mean? Well, for starters, Denis Cangemi, an IT project manager, and a developer, explains how version control gives you the reins over the documents’ life cycles.
Basically, thanks to version control, you can have an entire document history at your fingertips.
That means you can know at any time:
- What changes were made
- Who made the changes
- When were changes made
Why is that important?
Because, as we’ve mentioned at the beginning of this section, it allows you to roll back time to any point in the document’s history, from writing the first sentence to saving the final draft.
That can be very helpful when you or your team member makes a mistake, deletes something that should stay in the document, or any other of the countless wrong turns that can happen when creating something as complex and detailed as software documentation.
It can happen even to professionals like Josh Logozar, a system analyst at IG Wealth Management.
Version history has saved me a few times when I have made changes to documents that either I didn’t want to, or shouldn’t have made changes to.
Luckily, many documentation tools today allow you to see the document history and restore the document to one of its previous versions.
They also have an autosave feature that automatically creates new document versions whenever someone changes the document, which is very convenient.
For instance, below, you can see what document history looks like in Google Docs.
As you can see, multiple versions are available, and the highlighted one is restored from an earlier version.
Also, the additional data shows you when the document versions were created and who the contributors are (the parts that are blurred for privacy reasons).
If you use a modern documentation tool, all of those features are available to you and your team, so keeping a clear document history is simple.
All you need to do is use it to your advantage.
Manage Access to Documents
Document version control is much more manageable when you know precisely who can access which documents in the knowledge base and what they can do with them.
You are probably well aware of this, but it doesn’t hurt to have a refresher—documentation is a broad term, and your organization most likely has dozens, if not hundreds, of documents.
Not restricting access to documents in any way, even within your organization, can pose a possible security risk.
The team from Accusoft, a software development company, summed it up like this:
Without strong access control, it’s difficult to prevent any single person from altering, renaming, moving, or even deleting a document.
For example, although the Data Risk Report from Varonis focuses on financial services, it can give you an idea of the scope of documentation that employees can access.
According to their data, nearly two-thirds of companies have over 1000 sensitive files open to every employee, and about 60% of companies have over 500 passwords that never expire.
If you want to control how your documents change, who edits them, and how, you should have a tighter grip on your documentation than that.
Furthermore, various documents serve different purposes.
Particular departments or teams within the organization might find some documents vital, while others don’t have any need for them.
That’s why it’s useful to control access to documents. With more control over the document access, you can control what happens to the documents, who can change them, and how.
Documentation tools are particularly useful for managing access to documents because they usually allow you to control the level of access on a granular level.
For example, access control can look something like this:
This above is an example of what we’ve mentioned earlier about providing different levels of access to various departments or teams.
In this example, you can see that a software development team can read the documents in the Engineering Team section but not edit or write in it.
That is logical; software development and engineering teams work on similar issues and projects, so granting developers access to engineering documentation can be beneficial.
On the other hand, you can give permission to any other team you want.
However, you might consider whether, for instance, the customer support team has any benefits of having access to engineering documentation or if granting access to them can do more damage than good.
Controlling access to documents gives you more control over the document versions, which you can use to keep your documents safe and reliable.
Centralize Your Feedback Process
For successful document versioning, communication between contributors is crucial.
Regardless if there are three or 29 contributors to the document, they should communicate and collaborate efficiently.
That includes discussing the edits to a document, proposals on how to improve it, and giving and receiving feedback on each significant activity or change someone makes in the document.
The feedback process is an integral part of the collaboration, and it goes without saying that you should encourage it.
It’s a very effective way to assess how successful the previous versions of the document were in accomplishing their goals and to determine in which way the document should develop further.
Now, the question is how to make the feedback process as smooth and straightforward as possible for the entire team.
Messaging apps and email immediately spring to mind. Those are efficient channels of communication that most of us use daily, but are they the best option for centralizing feedback?
For example, if you opt for emailing back and forth with your team, that could easily end up like this:
This tweet sums up the problem with emails and similar communication channels, which is that it’s hard to engage every contributor in the communication.
If we add to that sometimes seemingly endless email threads with dozens of replies, replies to replies, etc., it’s easy to get lost in the communication and miss some important information.
So, where should you centralize document feedback? One excellent solution is in the document itself.
Why? Because everything is in one place, in other words, in the document that you and your team members work on anyway.
Furthermore, providing only one way for giving and receiving feedback is convenient because everyone knows exactly where and how the feedback process occurs, and there’s no confusion and switching between multiple feedback channels.
Many software tools allow you to write comments in the document itself and communicate with team members where everything happens anyway.
For instance, you can do that even in PDFs if you use Adobe Acrobat for Microsoft Teams.
As you can see above, you can highlight a part of the document and comment on it, which the rest of the collaborators will see.
That way, you can engage every contributor in the feedback process, especially if the documentation tool allows you to tag them so they don’t miss any important questions, insights, or messages.
Below you can see what that can look like.
Centralizing your feedback process in a document like that provides you with everyone’s opinions and comments in one place.
That makes tracking and managing the evolution of a document a much easier process.
Archive Old Versions
Modern documentation tools create many document versions—often more than you realistically need.
For example, many of them automatically save every change to a document and store it as a separate version.
And while that is valuable when you need to track the changes in documents or restore some of the previous versions, it can create difficulties in document organization and confusion among the team members.
That’s why archiving old versions of documents is beneficial. That way, instead of having access to a multitude of document versions, you can keep the ones you and your team need.
By archiving the surplus of document versions, you eliminate time-wasting and uncertainty when working with documentation—it’s easier to choose between three relevant document versions to work on than between five times that.
Here’s what Laurence Hart, information consultant and strategist, advises:
And while the time frame after you assess if old document versions are still valuable is up to you, we recommend the latter option Hart mentioned —hiding instead of deleting them.
That doesn’t have to mean literally hiding old versions from the world.
For instance, Esri develops geographic information mapping software and has relevant documentation on its website.
However, they also have a document archive with document versions that are no longer relevant to the current state of their products.
That way, the older document versions don’t mix with the new ones, and the possibility of confusion among the documentation team or users is minimal.
On the other hand, outdated versions still exist; they aren’t deleted for good, and anyone can still access them if needed.
Archiving document versions is easy if you use an excellent documentation tool like our own solution, Archbee.
Archbee allows you to create multiple versions of Spaces, which are essentially groups of documents.
That way, you can create a new version of a Space and all its documents while still keeping the older one accessible.
You can see what that looks like in the screenshot above. The links to the versions are clearly labeled, so there is no confusion about which is the newer one.
At the same time, you ensure that older and newer versions are separated and don’t end up in the same Space.
For managing a vast amount of documents, that can undoubtedly be a valuable feature.
Conclusion
Mastering document version control is critical for any organization that values efficiency and accuracy in its work.
If you follow the advice from this article, you’ll be able to keep your documentation organized, and up to date, and always have control over your information resources.
Luckily, today, you have software tools available that make document version control much easier than before.
So, there’s no excuse not to give it your best and keep your documentation in top-notch shape!
