The 8 Reasons Why Most Documentation is Doomed to Fail

Most teams are wasting a huge amount of time.

Time gets wasted because documentation is bad. And then more time gets wasted trying to fix the documentation by simply throwing a new tool and some additional content at it.

The cost to your team and business can be staggering:

• Mistakes are frequent
• Effort is wasted
• Delegation is slow
• New team members need a huge amount of support
• Manager time is wasted
• The opportunity cost is huge
• Stress levels are high
• Bottlenecks exist
• Key team members being unavailable causes issues
• Projects that try to fix these problems are expensive but have limited success

This all sounds exaggerated, yet over the last 15 years I’ve consistently seen the same story in teams and organizations of all sizes.

It almost leads to a conclusion that documentation will always be bad. But surely that can’t be true?

In 2018, I found the solution, and it turned out I’d previously been looking in the wrong place.

You’re never going to solve your documentation woes by throwing Google Docs, Confluence or Notion at the problem. Partly, because it’s not just the tool that needs to be fixed. And partly, because these tools lack some critical features needed to address the issues holding you back.

There are 8 big issues. By fixing these, we’ve solved the big issues we were previously experiencing in our business. And for the last 2 years, we’ve been sharing the same lessons with our customers, with incredible results.

Let’s dive into each of these 8 issues, and how they can be avoided.

1. It’s not obvious where content should go

You’ve got some kind of documentation tool, and it’s got folders or structure right?

That’s great, but sadly it’s not enough to make it obvious to everyone where content should go.

Let’s say I’ve just spotted that people are having trouble categorizing leads in our CRM.

It’s easy to start procrastinating:

• Should I create an article on how to categorize leads, or add it to an existing article?
• There isn’t an existing article… but it doesn’t feel like it’s enough to warrant it’s own page…?
• And we don’t currently have any other pages at this level of detail…?
• I’m not sure what folder it would go in… or how to make people aware of it…

Net result: You decide that it’s going to take too much time to fix, and so you don’t.

How do we fix this?

👉 All content should be tied to a documented process, policy, training, or onboarding. The only exception to this is short-lived content that doesn’t need to be kept-up-to-date (e.g. documents related to a project or meeting).

👉 Create placeholders for all of the processes, policies, training and onboarding you haven’t already documented. This makes it easy to add guidance when needed. The placeholders can also provide useful details such as “who’s the best person to ask for help with this process?”.

👉 Organize all of your content in a single location — the “home” for your processes, policies, training and onboarding. If you want to store some content in another tool, add links to your “home” so it’s still easy to find everything in one place.

2. It’s not focused on your biggest business problems

When your team decides it needs a new documentation tool, they can quickly provide a few stories that illustrate why your current solution is causing pain.

This is great — as a manager and leader, I love it when we can tie decisions to real problems that are holding back our business, or opportunities to grow.

Unfortunately, when the shiny new documentation tool is introduced, the team forgets about solving their biggest pain points, and is suddenly making a plan of how to document everything.

This is a recipe for disaster.

When you try to document everything, that is guaranteed to include things that the team doesn’t need to have documented right now.

Which means… investing a lot of time in content that’s not going to help any time soon.

Which means… it won’t be used.

Which means… the team’s going to quickly get demoralized, and stop documenting anything 🤦‍♂️

How do we avoid this?

👉 Prioritize the content that needs to be created as Low, Medium, High or Very high priority.

👉 Use these 5 questions to help you prioritize:

• Do we have any new team members starting soon? What guidance will they need?
• Is anyone going taking leave any time soon? What guidance will others need?
• Where is the lack of good guidance causing mistakes and wasted effort, and requiring a lot of management support?
• Which processes only have one expert? (— this is likely to cause issues if they person gets sick or needs a holiday)
• What processes could be delegated to help free up the time of key team members?

👉 If anyone tries to invest time in content that‘s Low priority, when there’s lots of High or Very high priority content needed… take away their keyboard until they’ve learned their lesson. (Or at least, have a constructive conversation and help them to redirect their energy 🙂)

3. It takes too long to create

The key to a great documentation is simple: a great return-on-investment.

So, when it takes a half-a-day to document and share something that will only save your team a few hours each year… well that’s not great.

We need to massively reduce the time it takes to document.

It shouldn’t take 4 hours to document a process and share it the first time.

It should take 5 minutes.

If we can get it down to 5 minutes, then a crazy good return-on-investment is almost guaranteed.

It also changes behavior. While finding an hour to create a document is challenging, finding 5 minutes… is not. Rather than getting parked for days, it’s something that can happen immediately after a meeting. Or even in the meeting.

How can we achieve this?

👉 A good document title makes a big difference. For processes, the document title should describe the task being documented (e.g. “Send an invoice” instead of “Invoices” or “Invoice management”). This immediately makes it clear what the document should contain and who will be using it.

👉 Start by listing out the high level steps in your process, training or onboarding. And then… consider stopping there! The high level steps is often enough. Only add additional guidance when it’s really needed.

👉 Use a tool that makes it really easy to document high level steps and add guidance to these (hint: AirManual‘s incredible for this!). Avoid any tools that require formatting to make things look good (— we’re looking at you MS Word!)

👉 Get comfortable with creating content that won’t be perfect first time, but will be much better than nothing. Set expectations that content will be iterated on — if we discover that more detail is needed, we can add it in later.

4. It’s not easy to use

When people think about documentation, there’s a tendency to think that it should be structured like pages in Wikipedia.

So you have a page about a broad subject, and this broken down into sections that relate to key areas of interest.

You can then brain dump into these sections, and job done — your knowledge has been shared!

This may be an effective way of getting knowledge out of your head, but unfortunately it’s not such an effective way of passing it onto others.

This is because your colleagues aren’t looking to become experts — at least not immediately. They simply need enough information to get the job done, and to meet expectations.

They want the information to be presented in way that makes it quick and easy to achieve this goal, without making mistakes.

So what’s the best way to do this?

👉 Processes, training and onboarding should all be documented as checklists, with guidance embedded into the checklist where needed. A checklist is the simplest way to communicate instructions, which is exactly what your colleagues want.

👉 The checklists should be interactive so your colleagues can choose to check off their progress. This won’t always be needed, but it’s important for those processes where the business impact of missing a step or making a mistake is high. It’s also very helpful for long checklists as you won’t have any problems resuming a checklist if you get distracted or take a tea break.

👉 Big processes should be broken down into bitesize checklists. Long checklists can be broken down into sections.

👉 Avoid having checklists that need to be handed over to different teams. It’s normally easier for each team to maintain their own checklist for their part of the process.

👉 The wording matters. Each step should be phrased as an action (e.g. “Prepare for the call” rather than “Preparation” or “Pre-call”).

👉 If you need to explain why you do something in a certain way, then avoid making users read this information every time they use the checklist. In AirManual, we provide collapsible help blocks for this exact situation. In other tools, you may need to link to another document that provides the context.

👉 You can use illustrations, photos and emojis to lighten up longer checklists.

👉 Use screenshots and videos sparingly. Sometimes they’re great, but they’re often not needed and will slow down experienced colleagues who have used a checklist before.

👉 Collect any information you need directly in the checklist. This isn’t possible with most documentation tools, but should be easy in tools that support process management using checklists.

5. No one’s held accountable for using it

Take a moment to think of that the team asked you to document something. And you spent hours preparing it. And you shared it with them.

And it never got used.

Everyone has been through this experience. And it sucks!

It hurts the person who wrote the content, and it hurts the team and business.

It’s not just the hours wasted on the content. It’s the impact this has.

If I spend 2 days writing a document that no-one ends up using, will I be bothered to keep it up-to-date? Definitely not. I’ll probably be a little embarrassed by it, and will be grateful when it’s forgotten about after a few months.

Will I be inclined to create further documents? Of course not. I’ve been burned by the previous experience. Time to leave it for someone else!

It’s often the person who was most enthusiastic about sorting out the documentation who gets burned the worst. It kills their motivation. It kills the positive momentum. And it kills the chances of long-term success.

How do we avoid this?

👉 As covered with issue 1: Make sure that all content is tied to a documented process, policy, training, or onboarding. The only exception to this is short-lived content that doesn’t need to be kept-up-to-date (e.g. documents related to a project or meeting).

👉 Set clear expectations that processes must be followed, policies must be adhered to, and training and onboarding must be completed.

👉 Manage these processes and make sure the team is living up to these expectations.

👉 Hold people accountable. If a team member doesn’t follow a process once, then find out why. If they repeatedly fail to follow a process without good reason, then it’s an employee performance issue to be managed accordingly.

6. No one’s held accountable for maintaining it

Is your documentation kept up-to-date?

Or has a lot of it gone stale? Is it now outdated and full of inaccuracies that the team are aware of but work around?

For most teams, there’s a lot of stale documentation, but no obvious way to tackle it.

In many cases, it’s not obvious who should do it. And when it is clear, it’s often a senior team member who simply doesn’t have the time.

The impact is bigger than the individual pieces of outdated or inaccurate content. These issues lead to team members not trusting that other pieces of content will be up-to-date and accurate. And once content isn’t trusted, it doesn’t get used.

How do we avoid this?

👉 Set expectations that all team members are responsible for keeping the content up-to-date.

👉 When aware that content needs to be created or updated, assign responsibility for who is expected to document and review the content. Where possible, try to avoid senior team members doing the documenting to avoid them becoming a bottleneck.

👉 Processes will naturally be reviewed each time they are used. Processes and training may not be reviewed as frequently, so manage these and review at least annually.

👉 Hold people accountable. If a team member spots an issue with a process but doesn’t share the issue or fix it, then find out why. If a manager isn’t ensuring the team’s documentation is maintained, then find out why. If they repeatedly fail to do this without good reason, then it’s an employee performance issue to be managed accordingly.

7. People feel uncomfortable suggesting updates

Let’s imagine that your CTO has created a process and policy on how to write clean code.

And there are a few steps that seem a little weird.

It looks like other people are using it anyway. So you assume there are good reasons for doing it in this way. And the CTO’s ridiculously busy, so you’re not going to bring this trivial issue up with him!

Even with holding the team accountable for keeping processes up-to-date, this is a scenario that I’ve had play out many times.

Sometimes, there was a good reason for the steps being written in a certain way.

But on other occasions, I’d written the steps in a rush, and forgotten something. Or, I’d written something which made sense a couple of years ago, but didn’t any more. Or, I’d simply been wrong and provided some guidance that caused more pain than good for the team.

Junior team members will always feel uncomfortable suggesting edits to documents that more experienced colleagues have written.

So how can we work around this?

👉 Make it easy to ask a question or suggest a change. Ideally, this can be done in the tool itself. Team members should more generally be encouraged to share questions and suggestions that can help the team improve. In our own teams, we use a simple document that we use a place for capturing these — we call it our issue tracker. We then prioritize and review the top few issues on our daily and weekly calls.

👉 Ask for feedback at the end of a process. Make sure any feedback is reviewed and managed.

👉 On your weekly team calls, review which processes are causing the team the most pain. Give team members the opportunity to share any and all issues they experienced over the last week. This can be part of a “retrospective” if this is already part of your weekly call.

👉 Make managers responsible for resolving issues where the team is unclear on whether guidance should be updated. This can either be by making a decision, or by consulting with another team or a more senior colleague.

8. Your team’s had no training

If you’ve made it this far, you’ve probably realized that great documentation doesn’t happen by chance!

At this point, I’ve shared over 30 tips, and most of them will not have been obvious.

So, you can’t just give your team a shiny tool and the instruction to document their best practices, and expect to get stellar results.

It’s not going to happen.

If you want to do this well, you need to spend time choosing an effective tool, creating placeholders, prioritizing content, assigning team members, and planning how to manage it.

So what training will they need?

👉 You’ll need to help the team to understand the expected benefits of this initiative:

• Fewer mistakes
• Less wasted effort
• Better delegation and less micromanagement
• New team members not needing a huge amount of support
• Freed up time
• Less stress
• Fewer bottlenecks
• No problems when key team members become unavailable (or take a holiday!)
• Solving documentation once and for all!

👉 The team will need to learn how to approach documentation so they get a positive return-on-investment on their time.

👉 The team will need to learn the most effective and efficient ways to document processes and keep them up-to-date.

👉 The team will need to learn how to review a process and share feedback.

👉 The team will need to learn how they will be be held accountable.

How to get started

Great documentation will transform your team.

I’ve experienced it into 2 of my own businesses, and over the last 2 years we’ve seen the same incredible impact happen for our customers at AirManual.

The best bit is that it doesn’t need to take a long time.

Using the tips above will much quicker than your previous documentation initiatives because the way you’ll start prioritizing and documenting content takes so little time.

When we work directly with our customers, we’ve found that we can roll out our framework in less than 10 hours.

By the end of it:

• The tool is set up
• Placeholders are in place
• Priorities are clear
• The highest priority content has been documented
• Processes are being managed
• Team members are trained

If you’d like support, then do arrange a demo below.

Alternatively, you can simply take the tips above, and start applying them to your own processes.

At the time of writing, you may struggle to find another tool that makes it as to document or use your processes. But there are workarounds of course!

Our mission is simply to help managers to get clear on what great documentation, process management and role onboarding looks like.

My hope is that this article has helped you with that. I’d love to hear your questions and feedback — you can reach me by email (paddy@airmanual.co) or on LinkedIn! 👋🙂