Have you ever written a document? What did your first draft look like? Anything like the final version?
Chances are, you’re looking at two completely different texts.
When writing documents, the content will change several times before you’re satisfied with the end result. To track these alterations, your best bet is document version control.
Version control is a way to manage all your document edits, and as such, it facilitates text composition—if done right.
The practice does have several pitfalls that must be avoided for optimal use.
In this article, we’ll present the most common document version mistakes and, more importantly, how to circumvent them.
Neglecting to Define Naming Conventions
As you create documents, you’ll have multiple iterations of the same text.
A technical writer will likely compose the first draft, then a subject matter expert and an editor will comb through the text and make the necessary edits, and, finally, a manager will approve the document.
Even though this workflow is straightforward, your employees could still easily misidentify document versions, with heavy consequences—imagine the fallout if the manager accidentally approves the first draft!
Therefore, to avoid such situations, defining the naming conventions is essential. That way, your employees can easily differentiate between document versions.
Generally speaking, naming conventions usually incorporate these guidelines:
- Using the same principal file name
- Using the same delimiter
- Using the same suffix
For clarification, here’s a visual representation of these rules:
Ideally, naming practices should remain consistent across all elements, as such cohesion significantly facilitates identifying document iterations.
You might also notice that these names contain two numbers (e.g., v3_01).
This is a helpful naming convention. The first number (here, v3) denotes the third majorly revised version of the document. As larger edits are approved, the first numeral grows.
The second numeral, on the other hand, marks minor revisions. Typical examples would be spelling mistakes, rearranging the sentence structure, etc.
Here’s an example of this naming process:
Just as the University of Aberdeen documented this naming convention, it’s worth your organization doing the same.
That way, everyone will have explicit, written guidance on naming documents.
The NHS is a good role model; they’ve also compiled a guide on handling document version control. Here’s an excerpt:
This particular rule differs from our previous example, further highlighting the importance of documenting naming conventions.
Each organization will have slightly different naming practices, as no standardized, set-in-stone rules exist.
As such, you want to ensure your employees follow your organization’s methods and not their personal preferences.
The easiest way to do so is to clearly define your naming conventions and then document them accordingly.
Not Backing up the Original Version
When working on software, it’s to be expected that plans will change. However, they might also change back.
Imagine you’re trying a new methodology— you’ve switched from Scrum to Kanban. But, after a trial period, you noticed you worked more efficiently in Scrum.
So, you revert to the Scrum framework.
There’s only one problem: all your supporting documentation has been rewritten. You don’t have any Scrum materials.
Such situations are why you should always back up the original document version. Otherwise, you risk permanently losing the source text.
With this in mind, Verizon advised the following:
Try maintaining a regular backup schedule, ideally daily or weekly; that way, you should easily remember to backup documents.
The occasional offline backup is also a huge help, especially for your most important iterations.
To make these backups as helpful as possible, all texts should include comprehensive information about themselves.
For example, this data is essential:
By clearly stating this information, it’ll be immediately apparent if the text is a rough draft, a final version, or awaiting review.
Furthermore, employees can tell at a glance whether or not it’s been approved.
Such information is invaluable, as you’ll clearly define each backup’s exact function and relevance.
However, it’s not enough to back up documents.
Retaining and storing these backups is equally vital. Cesar Bravo, the author of Mastering Defensive Security, has some guidelines on this:
Ideally, deleting documents should be complex enough to prevent any accidents.
The procedure should require more than one click, and only senior employees should have the credentials to remove a text.
You want to make the process relatively complicated, as it’s then less likely someone will delete something they shouldn’t have. That way, you’ll always retain backups of the original version.
Creating Multiple Revision Documents
In theory, document contributors should work on the most recent document version, as that iteration will be the most up-to-date.
However, sometimes just identifying the current document version can be a struggle.
Let’s say you want to revise your User Manual and find the following documents: User_Manual_John_comments, User_Manual_Mary_Revised, and User_Manual_v4.
With so many revision documents, there’s no way to recognize the most recent version.
Such disorganization is a huge time-waster, as you must comb through each iteration to extrapolate the correct version.
In fact, you might not be able to tell which document is the most recent; you might have to ask Mary or John for clarification.
Considering all these roadblocks, the following statistic makes a lot of sense:
Knowledge workers can spend over two hours looking for correct information.
Keeping multiple revision documents will only exacerbate the issue, as contributors waste time determining which version contains the right intelligence.
Considering these difficulties, Heidi May, an Operations Manager at Green Hat Consulting, emphasized the following:
With only one document in circulation, there’ll be no ambiguity about which text is correct, and everyone will know exactly which file to work with.
The easiest way to limit your revision documents to a single version is straightforward. Just follow the advice of Denis Cangemi, a Project Manager at FastCode:
Your best bet is to continuously store each older document version every time you update a text.
As soon as you prepare a new document version, ensure to file away the previous, now-outdated version. You should automatically manage your document iterations much more quickly.
With such efficient file storage practices, there’s no chance of multiple revision documents circulating. You’ll only maintain one dedicated version, eliminating any ambiguity.
Not Managing Access to Documents
Using a shared drive might seem like a fantastic method to ease document collaboration.
After all, the documents will always be available for all employees, and you’ll never worry about anyone not getting the needed materials.
However, this communal approach has several drawbacks. By allowing access to all colleagues, you risk inexperienced contributors mishandling important documentation.
For example, a new hire might sit in on a stakeholder meeting and misunderstand their requirements.
If that employee then alters the software requirements document, you risk building software the client didn’t ask for.
Because of such situations, managing access to your documentation (especially sensitive texts) is essential.
However, unfortunately, most organizations aren’t investing in access control. Look at these statistics:
Over 70% of organizations are neglecting access control procedures. The practice is clearly not a priority, despite its many advantages,
In fact, some studies have proved such practices significantly reduce the risk of documentation errors.
Here are the numbers:
By controlling which employees can access which documents, there’s less chance of inexperienced colleagues altering, renaming, moving, or deleting a document.
Your texts will be much more securely handled.
As for how to uphold access controls, there are several different strategies, but the graph below displays the most efficient approaches:
Using emails to control access credentials is the most popular approach, but it’s also worth monitoring your employees’ devices.
For security reasons, you don’t want company documents stored on personal devices, as this is a much greater risk.
Consequently, it’s a good idea to watch out for employees accessing documents from unofficial devices.
In addition to this, you might also restrict link-sharing as an extra precaution against unauthorized contributors.
All these measures are helpful and are great ways to manage access to your documentation.
Failing to Centralize the Feedback Process
One of the main reasons you’re even creating different document versions is contributor feedback.
You can hardly compose API documentation without consulting developers or outline your testing strategy without QA’s comments.
SMEs will review your document, and you’ll leverage their comments to improve the text. Consequently, their feedback is essential to creating a high-quality document.
To streamline this collaboration, managing the feedback in one centralized location is best. Ideally, this would be the same space as the document.
At least, that’s what Laurence Hart, CGI’s Director of Consulting Services, advises:
There’s no point in reviewers making a copy of the document, inserting their edits there, and then emailing the revised text.
Similarly, meetings to communicate feedback also shouldn’t be necessary.
Instead, all feedback should be submitted in one dedicated location.
One easy way to achieve this is investing in a documentation tool.
For example, with Archbee, contributors can communicate directly inside the document, leaving comments and even tagging others.
Here’s a preview:
With such in-line comments, you’ll have everyone’s feedback in one centralized, easily-accessible place. Consequently, there’s little chance of missing any suggestions.
Furthermore, you can collaborate on the text asynchronously with this approach.
Even if colleagues comment outside your working hours, their feedback will be waiting when you next log on.
Such a centralized approach is proven to work extremely efficiently. Jennifer Becker, the Team Lead of Customer Success at Filestage, can attest to this:
Centralizing feedback should significantly accelerate the feedback process, as you won’t be consolidating comments from multiple sources.
Instead, all the necessary information will be listed in a convenient, accessible location.
With such a clear overview, the feedback process will be much quicker, and you’ll gather all the comments you need effortlessly.
Neglecting to Archive Outdated Versions
We’ve already established the dangers of hosting multiple revision documents, as maintaining multiple iterations might confuse document contributors.
Similarly, it’s equally unproductive to host old document versions in the same space as the current ones.
You risk employees mistaking these outdated documents for current versions and then working with incorrect information.
Imagine if your employees accidentally consulted the 2020 remote work policies.
Those guidelines have likely changed since then, and your team members could easily start operating on incorrect assumptions.
Such obsolete document versions should be archived—securely stored in a dedicated location. That way, you’ll retain their information, but their content won’t confuse your team members.
This topic was also discussed on a Reddit thread, with one user offering a superb document archival strategy:
By hosting systematic documentation-centric meetings, you can consistently review your documents’ relevancy.
Outdated documents can then be archived on a regular basis as you continuously purge obsolete texts.
It’s worth noting that archiving should only be performed when you’re sure the document is no longer relevant.
After all, archival is the last stage of the document life cycle, as shown below:
Archiving entails removing a text from regular use and is helpful only if you’re certain that the document version isn’t needed. Remember: after archiving, no employees can view the text.
In some niche cases, destroying certain documents might even be best. Ron L., an experienced technological consultant, explains why:
While retaining documents is great in itself, thought should be given to how long you need the item. Storing items longer than necessary can add to storage costs, and even increase risk.
Consider contracts with former employees or confidential data from old clients. You no longer need to retain these documents, as you’ve ended your collaboration.
Therefore, to adhere to privacy laws and avoid unauthorized individuals accessing such sensitive data, you are within your right to destroy such documents.
However, in less extreme cases, where the document’s content is simply out-of-date, archival is the best solution to keep your documentation current.
Conclusion
Document version control is an invaluable writing tool. This practice helps you track changes to your text, so you can more easily manage all your documents.
However, like any other practice, there are some potential roadblocks that can impair its efficiency.
For example, keeping multiple document versions in circulation will only confuse contributors, and naming conventions must always be clearly defined.
That being said, if you can mitigate these issues, you’re well on your way to establishing a superb document management process.
With well-executed document version control, your texts will be high-quality, relevant, and helpful for all employees.
