A plan for improving outdated help documentation

Let’s be honest: there’s a good chance the help documentation for your product or service is probably out of date.

Before you feel defensive, know that you’re in good company. Most software vendors struggle with the same problem. Documentation has a habit of aging like milk, rather than wine; it happens faster than you think.

Your developers are building features, not writing help content. Your product is evolving with every sprint. If you have technical authors, they are tied up documenting the exciting new releases, rather than updating last year’s user guide.

Nobody means for the documentation to decay. But it’s all too easy for a few months to pass and you’re in a situation where half your screenshots show the old interface and your most popular help article refers to a feature you deprecated.

The damage compounds quickly:

• Support tickets increase because users can’t find accurate answers
• Customer satisfaction drops as people struggle with outdated instructions
• Your team wastes time answering repetitive questions that documentation should handle
• Prospects researching your product find incomplete or confusing information

There is some good news. Documentation debt, unlike technical debt, can be paid down systematically. You don’t need to rewrite everything overnight.

What you need is a clear plan, the right priorities, and a structured approach to both fixing what’s broken and preventing it from breaking again.

This guide will show you how.

How people find content

Below is a common scenario:

1. Search engines and LLMs scan and index your site
2. A person enters a question into a search engine or chatbot, and the search engines and LLMs direct them to a specific page on your site. They might also provide a summary answer based on your content
3. The person visits that page and reads the content
4. They have the answer to their question

This means:

• The content needs to be findable by search engines and LLMs
• It needs to be parsable by search engines and LLMs – the information design needs to enable them to scan the content
• The content needs to clearly answer the question they’re asking

The content needs to clearly answer the question they’re asking

“Every page is page one” is a design philosophy developed by Mark Baker for creating web-based help content. One of its key principles is that every page must be self-contained and understandable without prior context, because users may arrive from a search engine at any point.

Step 1. Scope the work to be done

You need to know what the problems are before you can fix them. You can get some indication from the number and type of support tickets – there will be some user questions that could have been answered by a help topic rather than by a support person. You can get anecdotal information from field engineers and customer success managers, although be careful not to focus only on those who shout the loudest. In addition to this, you’ll need to come up with a plan and break the work down into tasks.

Step 2. Ensure the LLMs and search engines can find the content

For your help documentation to be useful, it first needs to be discoverable. Search engines and large language models (LLMs) rely on specific signals and structured data to understand, index and surface your content. Here’s how to ensure they can find and properly interpret your documentation.

Add or fix the metadata

Metadata is information about your content that isn’t directly visible to human readers but is crucial for search engines and LLMs. For example:

• Each page should have a unique, descriptive title that clearly indicates what the page covers.
• Meta descriptions summaries appear in search results and should accurately describe the content.
• Use proper H1–H3 hierarchy to structure your content.
• Alt text for images. Describe screenshots and diagrams.
• Consider schema.org or similar markup for documentation.

Provide an LLMs.txt file

An LLMs.txt file is a standardised text file that helps AI systems understand your documentation. It gives LLMs an overview, key URLs, and the structure of your content.

# LLMs.txt for Acme Software Documentation

## About
Comprehensive documentation for Acme Project Management Software, covering installation, configuration, user guides, and API reference.

## Key Resources
- Getting Started: https://docs.acme.com/getting-started
- User Guide: https://docs.acme.com/user-guide
- API Reference: https://docs.acme.com/api
- Troubleshooting: https://docs.acme.com/troubleshooting

## Structure
Our documentation is organised into four main sections:
1. Installation and Setup
2. User Guides (organised by role)
3. Developer Documentation
4. Support and Troubleshooting

Provide a Model Context Protocol (MCP) server

MCP is an open standard that allows AI systems to securely access multiple data sources, versions and content repositories, ensuring LLMs can retrieve the most accurate information.

• Centralise documentation scattered across platforms
• Support version-specific documentation
• Control access and security

Ensure proper indexing

• Keep your XML sitemap updated
• Ensure robots.txt allows crawling
• Optimise for fast loading
• Avoid authentication barriers for public docs
• Strengthen internal linking

Step 3. Review the information design

Is the content scannable?

Most users scan rather than read. Use short paragraphs, bullets and clear structure.

Is it consistently structured?

Consistency helps users build a mental model. Use templates for:

• Concept pages
• Task pages
• Reference pages

Use consistent terminology

Avoid synonyms for the same concept across pages.

Apply consistent formatting

Use consistent styling for code blocks, notes, warnings and tips.

Maintain consistent navigation

Include breadcrumbs, previous/next links, and TOCs.

Are there clear subheadings?

Subheadings improve scannability, SEO and LLM parsing.

Does each page stand alone?

Follow the “every page is page one” principle we mentioned earlier.

Is the content accessible?

Ensure your content is fully usable with assistive technologies.

Can users find what they need?

• Implement strong site search
• Use clear navigation
• Add breadcrumbs
• Provide HTML and XML sitemaps

Review with fresh eyes

Use usability testing, analytics, support feedback and accessibility checks.

Step 4. Improve the content

Review and update each page for clarity, accuracy and completeness.

Step 5. Automate where possible

Use automation for broken links, outdated version numbers and terminology—but keep human oversight.

Step 6. Prevent it from happening again

Engaging a technical writing services company can help maintain ongoing quality.

If you have an overwhelming number of things to fix

Triage the work to be done

Focus on the most important and popular pages first.

Engage a technical writing team

Add temporary resources to get through the initial workload.

How Cherryleaf can help you

Technical writing services

Cherryleaf’s technical communicators can create or maintain documentation as a one-off project or on an ongoing basis. Contact us for more details.

Audits

Cherryleaf uses tools simulating user personas to analyse navigation issues and success rates. Contact us for a free analysis.

Training

Cherryleaf offers courses on technical writing and managing documentation projects using AI.