Product documentation is essential to any software on the market today.
It helps customers understand how to use the product effectively and efficiently, but it also provides valuable information to the company’s employees.
It’s an indispensable resource all around.
That is if you keep it updated.
Outdated documentation basically just takes up space because it isn’t relevant or accurate.
Luckily, this guide will provide you with ways to always keep your documentation up to date.
Let’s dive in!
Keep Documentation Close to the Code
One of the first things you should strive for if you want to make updating product documentation easier is to keep it close to the code.
Simply put, the more distance between the code and the documentation, the more likely it is that documentation will be an afterthought.
What do we mean by that?
For instance, if the documentation isn’t easily accessible, it’s possible that developers won’t bother updating it after they change a part of the code—and who knows who will do it and when.
On the other hand, if the documentation is close to the code, it’s more likely that the docs will be used and regularly updated.
Because of that, Omer Rosenbaum, co-founder and CTO of Swimm, advises coupling documentation with the code.
So, how close can you keep your documentation to the code?
If you look at the example of Twilio documentation, it’s possible to keep the two literally next to each other.
Twilio separated its documentation into columns. In the middle column are the textual documentation and explanations of the code examples, which occupy the column on the right.
For example, you can see below how readers can get to the part about creating an access token in chat and immediately examine the code with added comments for clarity.
The code in the right column isn’t just for show. The users can copy it, use it, and even choose between code in multiple programming languages.
That means Twilio’s team needs to keep it relevant and updated so it works as intended. And they also need to keep the documentation referring to it relevant and updated.
Luckily for them, they don’t need to waste time looking for that documentation—it’s a few moves of a computer mouse away from the actual code.
Keeping it that close makes it easier to update when needed, so it’s an idea worth considering.
Appoint Someone as the Document Owner
Do you want to keep your documentation updated, avoid confusion among your team members, and stop your docs from dissolving into collections of obsolete information?
If you do, you need to give someone the responsibility of maintaining your resources.
You might think that explicitly giving someone the task of updating the documentation isn’t necessary.
After all, there will always be someone who’ll take the time to work on the docs, right?
Possibly, but not necessarily. And if you want to ensure that your documentation is relevant and useful, you won’t settle for “possibly”.
There is a phenomenon called the diffusion of responsibility. Here’s how American Psychological Association explains it:
The diminished sense of responsibility often experienced by individuals in groups and social collectives.
In the context of keeping the product documentation updated, that means that the responsibility for updating it could fall to no one. In other words, everyone might expect someone else to do it.
That’s why appointing someone as the document owner is important.
By doing that, you give them the responsibility to keep the documentation up to date—they know it, you know it, and the whole team knows it.
The next issue is who to appoint. Ideally, it should be someone who loves doing it, as the Reddit user below describes.
That way, you wouldn’t have to worry about the quality of that person’s work.
The other possible solution is to have the product owner responsible for the product documentation.
As Alice Spies, an experienced customer success coordinator and consultant, points out, product owners have a great understanding of the project from the beginning, which allows them to approach the documentation holistically.
Regardless of who you appoint as the document owner, it’s helpful if that person has a system that helps them to update the documentation regularly.
Many software tools can help in making them accountable. For instance, Trello has an advanced checklist feature, which you can use to track Trello board tasks.
As you can see above, you can, for example, set the Calendar view and know when the documentation update should be completed and who is responsible for it.
The point is that, no matter which system for appointing you use, there is always someone who clearly understands that their task is to update the documentation.
Set up Notifications About Code Changes
As we’ve mentioned, the closer the documentation is to the code, the easier it is to maintain it.
Don’t underestimate the power of convenience. If you can make sure that something requires less effort, you should do it. That way, you increase the chances that the task will be completed.
That’s also true for updating product documentation. So, what else can you do besides keeping documentation close to the code and appointing someone to update it regularly?
You can remove the need to check if the code and the documentation are aligned by setting up a notification every time someone changes the code.
How does that work? There are various tools that can help you.
For example, the team from JetBrains automates notifications with a task tracker.
Above, you can see the automated email their tool creates and sends when a developer commits, pushes, merges, or does anything else to the code.
As Svetlana Novikova describes in her blog post, that sets the wheels in motion:
A technical writer reviews changes and accepts them or offers suggestions to the developer about what to adjust.
As you can see from JetBrains’ example, all you need is a software tool that will create notifications when the code changes.
Luckily, there are multiple tools to choose from.
For instance, Code Dog is a Slack app that sends notifications when there’s a pull request or other actions that need attention.
With a tool like that, it’s easy to track code changes and, therefore, easier to update documentation as needed.
The point is that code changes shouldn’t go under the radar.
If they do, the gap between the product and the product documentation will grow more and more until the documentation is no longer relevant or accurate.
Notifications can help in preventing that from happening.
Establish a Regular Update Schedule
There is more than one approach to keeping your documentation in pristine condition. Establishing an update schedule is one of those effective solutions you should consider.
The reason you should create and maintain a schedule for updating product documentation is straightforward—that’s a dependable way to ensure that your documentation will stay relevant and accurate.
And relevancy and accuracy are essential for documentation. Who would want to use resources that don’t reflect the state of the product? You probably know the answer.
On the other hand, if you regularly update your documentation, it will fit your users’ needs.
According to data from Zendesk, that’s crucial for users. You’ll be hard-pressed to find one that wouldn’t use your information resource if it provides them with what they need.
And how to ensure that the documentation constantly fits your users’ needs? You guessed it—by keeping a regular update schedule.
You can establish a regular schedule easily by using tools like page expiry notifier.
It’s available on GitHub as an open-source tool, and it runs the script once a day, finds pages that need updating, and sends a Slack message to the owner of each page.
It’s also customizable so that you can change various parameters. Below is an example of what the message can look like:
An even easier way to keep an updating schedule is to use features of your documentation tool.
If you use Archbee, you can set up document verifications and take care of your update schedule hassle-free.
You just select a team member responsible for updating the documentation, and if you followed our advice from earlier, you already have that person.
Then, they’ll be regularly notified when it’s time to check the document’s content.
You can see how that works in the video below.
Source: Archbee on YouTube
Establishing a schedule ensures that your documentation will always be updated.
And that’s necessary if you want to keep it useful for your users and retain their trust in you and your resources.
Encourage Team Involvement
One of the ways to keep your documentation up to date is to involve as many of your team members as possible in the task of maintaining it.
If you’re wondering why we’re now recommending encouraging team involvement after we’ve argued for putting one person in charge of updating the docs, let us explain.
Just because one team member is responsible for the relevancy of documentation doesn’t mean that the others shouldn’t contribute—on the contrary.
After all, according to data from the Queens University of Charlotte, 39% of employees in modern workplaces feel like people in their company don’t collaborate as much as they should.
What can increased collaboration mean for your documentation?
It goes without saying that your resources can significantly benefit from multiple points of view, diverse expertise, different levels of experience, and all the other factors that individuals can bring to the table.
Furthermore, with more team members involved, more of them know every detail of the product, which can reflect positively on how up-to-date the documentation is.
For example, take a look at the part of the documentation for Microsoft Visual Studio Code.
Visual Studio Code is a source code editor whose documentation is full of parts like the one above.
Clearly, to write and maintain complex documentation like that, you need a person with a high level of technical expertise, most likely a developer or software engineer.
That’s where encouraging team involvement can pay off.
Instead of waiting on that one technical writer with enough knowledge to write documentation like that or risking errors with contributors who don’t, a developer can jump in, write it, or at least give advice and proofread the documentation.
That way, the users will have it on time, and the accuracy also won’t be an issue. The team’s joint efforts can ensure that the documentation is regularly updated.
Conclusion
To summarize, keeping your product documentation always up to date is something you should undoubtedly invest your time and effort in.
Updated documentation helps your customers use your products effectively, enhances the overall customer experience, and boosts customer satisfaction.
Use this guide as a roadmap to ensure your documentation efforts are always on point.
‍
