A real-life scenario: Our docs are scattered; we don’t know what to trust

A collection of Word and PDFs in SharePoint … a Confluence wiki … the sales team’s folder of PowerPoints… training courses in an e-learning system. There’s loads of information about your product, but no-one knows the best place to start looking.

Information in different places overlaps but is inconsistent, so people aren’t sure what they can trust. Your teams can lose hours digging into all the information, but they’re still not confident they’ve found answers, so they end up needing to check with that internal expert who knows everything there is to know. In fact, many colleagues have given up on the documentation completely, and just shortcut their search by going straight to that over-stretched expert instead. 

Common causes 

The underlying cause here is often a classic case of organisational silos, often combined with a tactical approach to collecting product information – rather than developing a broader strategy. 

• People/organisation: different teams, using different tools, care about different audience … so they create different documentation and deliver it in different channels. We often come across situations where people have given up trying to find documentation in other people’s repositories, and just made their own collection, which inevitably adds to the problem by quickly going out of date. 
• Information design: there’s no organisation-wide approach (often not even a shared approach between different product teams). 
• Process and governance: quality checks are patchy, there’s no curation or no end-of-life plan: once published, documentation stays around forever, leaving a large volume of out-of-date information mixed in with more recent material. 
• Tools: people don’t have access to all the repositories – so they create their own collections. For example, the marketing team can’t access the product user documentation site, so they don’t know that the information they need is in there.  

Solution

The most comprehensive solution is to implement an organisation-wide strategy for collecting product information – a “source of truth” that the rest of the organisation can draw on. Teams can still create their own documentation where needed, but everyone can always refer back to the source of truth for accurate and up-to-date information.  

But how to avoid this source of truth becoming just one more failed initiative, which turns into yet another place for people to look?  

1. Identify the essential types of information, and allocate responsibility for each.  

Implementing an organisation-wide product-information strategy is often associated with a single person or team designing and owning the set of information that needs to be collected, but that doesn’t mean all the documentation has to be created by that individual or team. A good first step to choosing an owner for a type of information, is to identify the source of that knowledge within the organisation. The closer you can move responsibility towards that source, the better the chance of collecting that knowledge. Your organisation can still have its silos, but there’s more clarity about what those silos need to contribute to shared knowledge.

2. Start with an MVP. 

This doesn’t have to mean throwing away all the old docs and writing new ones. A good first step is often to create a catalogue of the best information that currently exists. Once you’ve identified a minimal set of essential information, you can use a simple template to link to the best current documentation that contains that information (even if it’s not perfect). If there’s really nothing that comes close currently, be sure to make that gap clear, so people know they can stop their search and avoid wasting time. 

3. Make it as easy as possible to create and maintain source-of-truth information.  

Remove any barriers and duplicated effort. For example, configuration information can be automatically pushed into the source of truth from developer notes (using a template completed at the end of development) or from design specifications, particularly in spec-driven development. Product managers can add use cases manually, while AI can generate user documentation, supervised and quality-checked by a technical writer.

Identify the information needed and the source of that information, and it’s often straightforward to identify a simple way to get the information to where it needs to be.  

4. Rely on tooling, curation and editorial skills to create the deliverables you need.  

Your source of truth will contain the “official” state of knowledge about your product. But it probably won’t contain all the formats and combinations of information you want to make available to your partners and customers. You may be able to automate creating these deliverables from your source of truth – for example, building user guides from specified combinations of information, or making use of AI to generate feature guides in the format you need. Or you may find people continue to manually create documents that draw on the official information (in these cases, they will of course need to think about how they’ll monitor the source of truth for updates, so they maintain those documents). 

5. Review the toolset for finding information.  

Since our daily lives first started to revolve around sitting in front of a computer screen, we’ve been hearing of solutions to help cut through the enterprise knowledge problem. From enterprise search across multiple repositories and file types, through SharePoint or Wikis to collect all our knowledge in one place that can be easily searched, to AI-assisted search or Copilot-style chat. The solution outlined here doesn’t remove the need for this type of solution: documentation is going to continue to proliferate. But by designating the official source of truth, we’ve defined the reliable place to start looking. Whatever tooling you use to help people, it will be useful to make sure it distinguishes between this official source and all the other documentation. 

Outcome 

People know where to go to find information that they can either use as it is or make use of to build (and keep up to date!) other documentation. 

Bonus: no organisation ever has all the information that everyone needs. But improved architecture, search (and content) at least mean that they know when to stop wasting their time looking: because a good source of truth will make it clear what information doesn’t exist, as well as give good access to the information that does.