A real-life scenario: Our docs can’t keep up with product development

Your User Guide hasn’t been updated since the big UI rework last year. No one’s sure what made it into the Config Guide from the last few releases. And Professional Services have some great onboarding documents, but they made them last year and haven’t had time to update them.

Your teams are trying to bring everything up to date, but they’re also already involved in planning and implementing the next product updates… 

Common causes 

The obvious cause is that the people with knowledge and the people who are good at explaining don’t have enough time allocated to get this done. But that doesn’t mean the best answer is to put more resources on the job. Dig deeper into the causes, and there are often other things going on that also contribute to the problem. 

• Process: does information about what’s been implemented get captured anywhere? Are docs included in the planning of product updates? Are ownership and responsibilities clear, especially around communication about changes to product, and involving the right people in updating docs?  
• Tools: tools that aren’t set up right or aren’t suitable for your documentation require lots of fiddly manual formatting and copying and pasting (if you’re using Word or InDesign, there’s a strong chance this is you). The best tools include features to enable automation or AI support, but many tools used to make documentation don’t, so everything takes longer than it should.
• Information design: are you too ambitious about the scope and depth of documentation? Do you have documentation scattered across multiple unrelated systems, which updating for a single feature has to be done in several places? Is each piece of documentation unstructured or not templated, so it takes a long time to even work out where to add updates?  

Solution 

There’s usually a combination of different causes for this problem – as listed above – so of course, picking out the solution depends on exactly what the cause is in a particular context. A proper analysis exercise can dig into what’s really going on. 

But in most cases, a pragmatic place to start is the following steps:

1. Define the process for creating documentation 

Not just the general process, but pin down the details. In particular: 

• How, where and when will info about what’s changed be communicated?  
• Who’s responsible for updating docs? 

This isn’t an easy one, and often exposes gaps in time and skills. But without it, it’s always going to be hard. The good news is that going through the process of defining the process often results in finding ways to make it easier to keep docs up to date. For example, we often see that the people with knowledge don’t get around to writing it down because they’re overwhelmed by the scale of the task. Whereas in fact, the delay might be based on incorrect assumptions about what information is needed – which can be solved with a simple template that makes it clear that the required input is much more limited. 

2. Rationalise the information design 

This involves looking at what types of content you’re making, the scope of the documentation, how information is organised, and how the documentation is delivered to readers. 

• Define the content types and make some templates or examples of “good”. Good structures make it so much easier and faster to update, especially if you can avoid the need to duplicate any information. Conveniently, these structures are helpful for human readers , search engines, and AI to find useful information too. 
• Define the priorities. An MVP (minimum viable product) approach is good for this: what type of information is most important? Which outputs are required (KB, Help Centre site, PDFs…)? Do you really need all of these? But don’t limit this to thinking only about what documentation you make: also consider what quality level it has to achieve. For example, perhaps your end-user documentation has to be written to be absolutely clear and polished, but your administrator or reference documentation can be a little rougher, as long as it’s technically accurate. 

Outcome 

The combination of process and information design makes the goal of keeping documentation up to date more achievable.  

Perhaps you’ll find that with the current team availability, tools and process, you can only ever make the MVP. That’s not ideal … but an up-to-date, reliable set of core information is significantly more useful than a wider set of documentation, where no one knows what they can trust.

The concrete definition of what has to happen enables clear communication and reporting about progress and blockers. And as a bonus, along the way, you’ll also have identified exactly what needs to happen so you can apply this approach more widely in future.