Documentation

  |  
22 Min Read

How to improve an existing documentation system

Congrats on having an existing documentation system! This is a rare accomplishment for many companies!

As companies grow and employees change jobs, a documentation system can become out-of-date and less useful, unless maintenance processes are in place, including the roles of each team member. You likely found this blog since you have some sort of existing documentation in place, but you realize it could use improvements to efficiently keep it up-to-date and useful for enabling your teams.

Improving an existing system will depend on what you need to improve, by identifying what’s not working about your current system.

Here are the steps to follow to improve your system:

  1. Perform User Research
  2. Complete an Audit
  3. Determine the Changes to Make
  4. Start Making the Changes

Remember, the documentation system is NOT just the tool where you store documentation (Notion, Google Docs, etc.).

The definition of 'system' in Oxford dictionary:

  • a set of things working together as parts of a mechanism or an interconnecting network.
  • a set of principles or procedures according to which something is done; an organized framework or method.

The many parts of a documentation system include managing time management, project management, communication routines and policies, roles & responsibilities, storage tools, and more.

Create or improve your system with a focus on people & processes first, then tools.

If you skip all this system work, and go straight into choosing a new tool and expecting the tool to work miracles all by itself - that is likely to fail. And I don’t want you to fail.

It would be nice if a magic bullet tool did 100% of this work for you. If you could just buy it, and then a whole knowledge base of documentation that is automatically updated all the time will magically appear and maintain itself. But we’re working with humans, and human behavior, so it is not realistic to expect a tool to solve all the problems.

Now that we're clear on what this documentation system involves, let's discuss how to identify and complete the improvements to your existing system.

 

The content of this blog is from my workshop and course on documentation

I also discussed these concepts in a webinar for Operations Nation on how to set up your company for success by getting the right documentation systems in place.

Perform User Research

Improving an existing system will depend on what you need to improve, understanding what’s not working about your current system.

You may have ideas of improvements that you want to make, but it is important to get other users’ (and other roles) opinions.

Do user research!

Not only will this user research, or needs analysis, help you uncover issues you may not have known about that are contributing to the system issues, but you will also help people become aware of potential changes and make them feel involved. This is a change management step, so they will be less likely to resist the upcoming changes.

A common reason for seeking improvements to a system is when people are not currently using it, or using it correctly. This could be your first research question to investigate.

Why are people not using the existing system, or using it correctly?


A few possible reasons:

  • The information is outdated, so they can't trust it and it is not useful.
  • The documentation is not written clearly, so it is not useful. 
  • They can’t find what they need, they don’t know where to go, it’s spread out.
  • They were never trained. There was not enough communication on HOW to use it. 
  • They don’t have the right permissions in the tools, so they cannot use it.
  • What’s in it for them? No one ever communicated the value of WHY they should use it.
  • What are they doing instead of using documentation? Is that working well? This is a good line of questioning to follow up with.

But don’t guess at these answers, ask!

Do surveys and live interviews to find the root cause(s) of the issues, not merely identifying the symptoms.

You could potentially have a team meeting about why is no one using documentation, but people may not want to speak up in a group setting about something they may have been doing “wrong.” This would depend on how psychologically safe your culture currently is.

As mentioned above, asking team members in interviews and surveys will also help make them aware of future improvements coming later, which they will be less likely to resist if they feel heard and involved in the decisions.


Complete an Audit

You will also want to audit the existing documentation systems. 

This could be done at the same time as user research. Maybe you have time when you’re waiting to hear back from people when scheduling interviews or awaiting survey responses.


The timing of this audit is tricky because you may not have a clear idea of WHAT to audit until you get some responses from the user research. And you may not know the best questions to ask in the user research until you uncover some information in the audit. Therefore, both tactics may evolve as you go along in this process. You may do several rounds of user research and audits, getting closer and closer to the root cause of the system problems.

Audit the existing state of all parts of your documentation system -- time management, project management, communication routines, storage tools, roles & responsibilities, and more.

Documentation system items to audit

Some of the things to audit include finding and ... documenting :) : 

  • What is outdated
    • Can it be minor updates or should it be archived? 
  • Which articles are used or edited more often?
    • Depending on your storage tool, you may be able to see which articles are used or edited more often. Include that type of information in your audit documentation.
  • What needs to be added? What types of documentation are missing?
  • Are there missing categories or subcategories? Has your company grown to include new teams, who need their own category? 
    • This was common at my last company, as it grew often, so I was recategorizing documents as new roles were created. 
  • On an individual article level – does your template, structure, or naming convention of the documents need to change?
  • Is the time & task management systems for documentation effective? Why or why not?
  • Are communication processes clear and are people using them? Why or why not? Do you have the processes documented?
  • Audit your roles – if you have roles set up!
    • If you don't have roles, setting up roles should be added to your improvement plan. See the possible documentation system roles in this blog. 
    • Maybe the problem with your existing system is that it relied on one person. Maybe everyone was reliant on you, perhaps the one ops person in the company, to do it all and make sure it was always updated. That is not realistic since you wear a lot of other hats besides chief documentation officer!
    • Another common issue is managers or leaders not giving their teams time or accountability to complete their roles in documentation -- because the roles and responsibilities were not clear.
  • Is the storage tool the reason people may not be using it? Does it lack the permissions or features needed, such as integrations with tools your team uses daily? Are people unsure about which tool to use, so the company is using 23 different knowledge management tools?
    • Don’t jump right to this and think you’ve solved the problem if you replace the documentation storage tool! Tool adoption is difficult and could introduce additional change management issues besides all the behavior changes for other parts of the system.

Determine Which Changes to Make: Communicate & Plan

Use your findings from the user research and the audit to plan out the improvements to your system.

Important: Don't make this plan or prioritize the potential changes in a silo by yourself.

Ask other influential leaders or team members to help. This will help with change management, to get their buy-in so they will champion this plan and not resist it. Involving other managers or leaders in this process will also help motivate them to ensure their teams are using this system, performing their assigned roles and setting a good example for their teams to follow.

Communicate, communicate, communicate before, during, and after planning. 

Communicate the plans, and communicate WHY the changes will benefit individuals, teams, and the company.

For example, if the biggest change is centralizing the documents in one tool, unless it is a new tool for everyone, some people will have to change their habits and others may not. The people who have to change their habits and use a new tool may resent the people who do not need to change. Keep reminding and showing and proving the benefits of centralizing the documentation.

 

Start Making the Changes 

Make sure you have documented (!) how your system works, using the best practices for documenting processes including using videos, text, and context. For example, create a wiki/article on "How we manage and maintain our knowledge base." (Click to see a cleansed example of a wiki I made at a previous company, which doesn't include all the best practices I've learned since then, but could still be a helpful example.) Link this document in both directions to the "How to create documentation and use the knowledge base" documentation you should also have available for reference and training your team. Thanks to Joel Primack at RevOps Co-op for reminding me of this important note!

Begin making the changes to your systems, as you continue to communicate what is happening, has happened, and will happen. As you make start making updates, keep the documentation about your system updated, too. This will help train people as you roll out the changes, and instill trust that you're "walking your talk" and keeping documentation up-to-date and useful.

You may want to begin with a pilot or test group of people, perhaps one team or department will be more likely to accept changes and be willing to be a test group. Working with this team to roll out the changes over a month or more could help you identify potential issues with your planned changes and learn how to implement these changes more smoothly when you roll out the plan to other departments. Using a pilot group will also help you gain champions in the changes and prove the success of the plan, which you can communicate to help gain buy-in from the other teams later on. These tactics will help you be more successful in improving your existing documentation system across the company.

 

 

Additional help

You don't have to take your documentation journey alone.

process documentation on demand course

Documentation live course

For the most help in starting or improving your documentation, I have a 2-week, 4-session live course which is offered quarterly:

Documentation live workshops

If you only want help with one specific part of the documentation process:

I have 2 live workshops based on a session from the above course. They are hosted during the months the 2-week course isn't running.

Templates

If you're not ready for a course yet, the workbooks and templates from the course are starting to be available for purchase. 

 

Other resources:

Topics:   Documentation