Documentation infrastructure is easy to ignore until an engineering audit puts a number on it. When two engineers spend roughly 30% of their time maintaining builds, deployments, search indexing, and broken documentation pipelines, the cost is no longer a background annoyance: it is a measurable 0.6 FTE tax on product delivery.

That was the central issue raised in a recent r/SaaS post from a team evaluating whether to keep maintaining its own docs stack or move to a managed platform. The team also found that about 40% of support tickets had answers already documented somewhere—customers simply could not find them. The post offers a useful framing for larger SaaS companies: documentation is not just content. It is a retrieval system, an operational system, and increasingly an interface for AI agents. (reddit.com)

For companies with hundreds of engineers, the question is not whether docs matter. It is whether the current documentation infrastructure is producing enough leverage to justify the operational burden it creates.

The real documentation infrastructure problem

Most teams initially think of documentation as a website with a search bar. In practice, a production docs operation contains a much larger chain of systems:

Source repositories, CMSs, or Markdown files
Build tooling and deployment workflows
Preview environments and versioning rules
Navigation, information architecture, redirects, and analytics
Search indexing, ranking, synonym management, and freshness checks
API-reference generation and changelog publishing
Access control for private or partner-facing materials
Support workflows that link answers back to relevant pages
Structured data and AI-accessible formats

A breakdown in any one layer can make otherwise excellent content effectively invisible. A guide can be technically correct but obsolete in search. A reference page can be current but buried behind unclear navigation. A helpful troubleshooting article can exist, but a support agent may still write the same answer manually because the customer never located it.

That distinction matters because teams often diagnose a discovery problem as a writing problem. They respond by commissioning more articles, asking engineers to add more detail, or expanding the knowledge base. But if users cannot retrieve the correct answer in the moment they need it, publishing more material may just enlarge the pile.

The r/SaaS audit illustrates this clearly. The organization did not discover that 40% of tickets were undocumented. It discovered that a large share had already been answered in existing material. That points to a findability failure: search quality, content architecture, contextual linking, stale pages, weak query understanding, or all of the above.

Why 0.6 FTE is more expensive than it looks

The headline number in the original post—two engineers each spending about 30% of their time on docs operations—sounds manageable at first. But a 0.6 FTE maintenance load has costs beyond the percentage on a spreadsheet.

Direct opportunity cost

The obvious cost is feature work not completed. If a fully loaded engineer costs a company $200,000 to $300,000 annually, 0.6 FTE represents a meaningful annual expense before considering infrastructure bills, incident time, or management overhead.

More importantly, this work often falls on people capable of higher-leverage product, platform, developer-experience, or reliability work. A senior engineer spending an afternoon debugging a broken docs preview is not necessarily doing unimportant work. But that work should be intentional and strategically differentiated—not accidental toil created by a fragile publishing system.

Interrupt-driven work compounds the tax

Documentation infrastructure failures tend to arrive as interruptions:

A deployment breaks before a release.
Search stops indexing newly published material.
A migration changes URLs and creates support-impacting 404s.
Generated API docs fail because a schema changed.
Permissions expose the wrong content or lock out a customer.
A stale page becomes the top search result for an important query.

Interruptions are costly because they fragment attention. A team may estimate the maintenance burden as a few hours per week, while undercounting diagnosis, coordination, review, postmortems, and the mental cost of switching out of planned work.

Support volume obscures the second bill

The engineering cost is only one side of the ledger. If customers open tickets for issues already resolved in documentation, support absorbs repeatable work as well. That creates slower first responses, longer queues, and more opportunity for inconsistent answers.

The problem can also distort roadmap planning. Product teams may interpret repeated support questions as demand for a new feature when the immediate issue is that users do not know an existing capability exists or cannot complete its setup. Good documentation does not eliminate legitimate product gaps, but it helps distinguish product friction from information friction.

Documentation search is a product experience, not a utility

Search is often treated as a checkbox: install a provider, add an input field, and move on. That approach is increasingly inadequate for technical SaaS products with dense documentation, multiple versions, overlapping concepts, and users who describe problems differently from the team that wrote the docs.

A customer might search for “emails not sending,” while the relevant documentation uses terms such as “domain verification,” “suppression,” “webhook event,” or “API key permissions.” Literal keyword matching alone may not bridge that gap reliably.

What a useful docs search experience must do

A strong documentation search system should do more than return pages containing the typed words. It should help users reach an answer with minimal interpretation.

At a minimum, evaluate whether search can:

Understand intent and synonyms. It should connect user language with product terminology, error messages, acronyms, and common misspellings.
Prioritize authoritative and current content. The right result should outrank an old announcement, changelog entry, or loosely related blog post.
Respect versions and audience. A user on an older SDK, a self-hosted edition, or an enterprise plan should not be sent blindly to irrelevant instructions.
Surface answer-level passages. A result that opens at the relevant section is more useful than a generic page title.
Handle zero-result and low-confidence queries. These are valuable signals for content and product teams, not dead ends to ignore.
Measure successful retrieval. Search click-through is not enough; teams should track whether searches lead to fewer follow-up searches, fewer tickets, and higher self-service resolution.

AI answers can help, but only if retrieval is trustworthy

An AI assistant on a documentation site can reduce the work required to translate a question into the right search query. Instead of browsing six pages, a user can ask, “Why is my webhook signature failing in Node?” and receive a concise answer with links to the relevant reference and troubleshooting steps.

But an AI layer does not repair poor source material automatically. It can magnify problems when its retrieval corpus includes outdated migration guides, contradictory versioned pages, incomplete examples, or inaccurate support content. The quality bar must be higher than “the chatbot responds.”

A useful AI docs assistant should cite its underlying pages, distinguish documented facts from inference, avoid inventing configuration options, and make escalation easy when it is uncertain. Teams should also test it with real support queries—not only idealized prompts written by the documentation team.

The 40% ticket finding: how to turn it into an operating metric

The most actionable detail in the source post is the support team’s ticket tagging. If 40% of requests were answerable from existing docs, the company has already created the beginning of a business case.

The next step is to turn that one-quarter snapshot into an ongoing measurement system.

Build a documentation deflection taxonomy

Do not classify tickets only as “documented” or “undocumented.” That binary hides the reasons documentation failed. Add categories such as:

No relevant content exists: A genuine documentation or product gap.
Content exists but cannot be found: Search, navigation, or information architecture failure.
Content exists but is unclear: The page needs better steps, examples, screenshots, or error-specific guidance.
Content is stale or incorrect: A governance and ownership failure.
User needed account-specific help: Documentation may explain the process, but support intervention was still required.
User did not attempt self-service: An in-product discoverability, onboarding, or support-routing issue.

This turns support tickets into research. Rather than guessing what customers struggle with, a company can quantify where the self-service journey breaks.

Measure the full funnel, not pageviews

Pageviews are a weak proxy for docs effectiveness. A high-traffic page may mean it is useful, but it may also mean users repeatedly hit a confusing problem.

A better dashboard includes:

Searches per active customer or per documentation session
Zero-result rate and low-click query rate
Search reformulation rate, meaning users search again after a result
Top queries that lead to tickets
Ticket rate for documented issues
Time to publish or update documentation after a product change
Content freshness by product area
AI assistant answer acceptance, escalation, and citation-click rates
Support contacts per successful activation or integration

For an email API company, for example, a spike in searches for “SPF,” “DKIM,” “bounce,” or “sandbox” may show onboarding friction before a support queue reveals the scale of the issue. Better explanations and guided setup can reduce support load, while reliable reference material makes integration easier for developers working from your API setup documentation.

AI-ready documentation: separate the useful from the hype

The original post also raises a newer concern: its docs are not prepared for AI agents. It mentions the absence of llms.txt, an MCP server, and structured content at a time when developers increasingly use tools such as Cursor and Claude Code.

This concern is directionally right, but companies should avoid treating every emerging convention as a mandatory checklist item. “AI-ready” is not a single implementation. It is a capability made of several layers with different audiences and different levels of maturity.

llms.txt is helpful metadata, not a magic discovery switch

The llms.txt proposal describes a Markdown file that gives language models a curated overview of a site and links to deeper, machine-readable documentation. It is intended to make large or complex websites easier for language models to navigate at inference time. (llmstxt.org)

Publishing llms.txt can be a low-cost, sensible addition for public developer documentation. It can provide a clear starting map, identify canonical reference material, and point agents toward Markdown versions of important pages.

However, it is a proposal rather than a universal, enforceable web standard. It will not fix poor information architecture, stale content, blocked pages, or missing technical detail. A company should publish it because it improves clarity and machine navigation—not because it expects an immediate ranking boost or guaranteed usage by every AI product.

A practical llms.txt file should include:

A short description of the product and docs scope
Links to canonical getting-started, authentication, API, SDK, migration, and troubleshooting materials
Links to version-specific reference locations where appropriate
Guidance on which pages are authoritative when duplicates exist
Links to Markdown or text-first formats where available
Clear exclusion of deprecated product areas

Structured, stable content is the foundation

The more important work is making documentation consistently structured. That means stable URLs, meaningful page titles, semantic headings, explicit prerequisites, complete code examples, version labels, canonical links, and clearly marked deprecations.

For API companies, it also means treating schemas and reference documentation as products. OpenAPI definitions, typed examples, error-code references, webhook payload definitions, authentication guidance, SDK-specific quickstarts, and changelogs should be maintained with predictable ownership.

An agent can only use what it can retrieve and interpret. If a deployment guide has an ambiguous title, hides key requirements in a screenshot, omits error behavior, and conflicts with a newer blog post, an AI assistant will inherit that ambiguity.

MCP is different from publishing docs

Model Context Protocol, or MCP, is an open protocol for connecting AI applications to external tools and data sources. It is designed for use cases where an AI client needs structured access to tools, resources, or actions—not merely a page to read. (modelcontextprotocol.io)

Cursor documents MCP as a way to connect its environment to external tools and data sources, while Claude Code provides guidance for adding and using MCP servers. (cursor.com)

That makes MCP potentially valuable for documentation, but only in the right form. A docs MCP server could allow an approved AI client to search canonical documentation, fetch a specific version of an API reference, retrieve code examples, or inspect a changelog. For authenticated customers, it might eventually expose tenant-specific configuration guidance—provided permissions and security are properly designed.

But running an MCP server just to reproduce a public search endpoint may be needless operational complexity. Teams should first ask what unique, structured capability MCP enables that a static docs site, downloadable reference, or well-designed search API does not.

A practical AI-readiness stack for developer docs

Instead of starting with a vague objective such as “make our docs agent-ready,” build a layered plan. Each layer should deliver useful outcomes independently.

Layer 1: Canonical public documentation

Make the normal human docs experience excellent first. Ensure that the current version is obvious, deprecated material is labeled, URLs are durable, docs are indexable where appropriate, and the primary workflows are complete.

This is where most support deflection value comes from. It also gives AI systems cleaner, more reliable source material.

Layer 2: Machine-friendly representations

Publish text-first and structured sources where they make sense:

Markdown or clean HTML documentation
OpenAPI specifications
JSON schemas for webhooks and event payloads
Code samples that are tested in CI
llms.txt as a curated entry point for public documentation
Sitemaps, canonical tags, redirects, and version metadata

The goal is not format proliferation. The goal is to make the authoritative material easy to parse, retrieve, validate, and maintain.

Layer 3: Retrieval and answer quality

Improve site search and, where justified, deploy a cited AI assistant. Build an evaluation set from real tickets, failed searches, onboarding transcripts, and product terminology.

Use this set to test whether a system retrieves the correct source, produces an accurate answer, identifies uncertainty, and links people to the next step. Treat evaluation as continuous because product docs change constantly.

Layer 4: Governed agent access

Only after the content and retrieval fundamentals work should a company consider a dedicated docs MCP server or other agent-facing interface. Start read-only. Scope access narrowly. Require authentication where appropriate. Log usage. Rate-limit requests. Review what data and actions are exposed.

This staging matters because agent integrations expand the security and reliability surface. The MCP specification itself emphasizes integrations between LLM applications and external tools and data sources; that usefulness is precisely why teams need clear authorization, auditing, and blast-radius controls. (modelcontextprotocol.io)

Managed platform vs. self-hosted docs: the real decision

The source post asks whether migration pain is worth it for an organization in the 300–500 engineer range. There is no universal answer, and the team size alone is the wrong deciding variable.

The better question is: does your documentation system provide a strategic advantage that is worth its operational cost and reliability risk?

When self-managed documentation can make sense

Keeping a self-hosted or heavily customized system is reasonable when several of these conditions are true:

Documentation is deeply intertwined with proprietary product workflows.
You need unusual tenancy, regional hosting, compliance, or access-control requirements.
You have an established platform or developer-experience team that owns docs infrastructure explicitly.
Your content pipeline is reliable, well-observed, and inexpensive to operate.
Your custom search, versioning, or API-documentation experience is materially better than available managed tools.
The system is a deliberate platform investment rather than an inherited collection of scripts.

The key distinction is ownership. “We have a custom stack because we built it years ago” is not strategy. “We operate a custom stack because it enables controlled, differentiated workflows that our customers depend on” may be.

When a managed platform is usually the better choice

A managed platform becomes compelling when the company’s internal effort is dominated by commodity concerns: builds, hosting, previews, search indexing, redirects, access basics, and keeping plugins compatible.

Signs that migration is likely worth evaluating include:

Docs incidents repeatedly interrupt product or platform engineers.
Search requires frequent manual repair but still performs poorly.
Content publication is slow because engineers are needed for routine changes.
Support has proof that answers exist but users cannot locate them.
Documentation quality varies because ownership is unclear.
The company cannot reliably measure search success, content freshness, or ticket deflection.
The roadmap includes AI-assisted support or agent-facing developer workflows, but the foundation is brittle.

A managed service does not automatically solve content governance or answer quality. It does, however, let the team purchase maturity in areas that are rarely product differentiators.

How to compare platforms without falling for feature checklists

A procurement spreadsheet can make every docs platform look similar. Most will offer Markdown support, a search box, a theme, analytics, and some form of AI feature. The difference emerges in operating reality.

Build a weighted evaluation around your actual failure modes.

Use real tasks as the test suite

Ask each candidate platform to demonstrate workflows based on recent incidents and common support tickets:

Publish a release note and update three affected setup pages.
Generate a preview for a pull request and collect review feedback.
Redirect a deprecated URL without harming search or analytics.
Search for five real user queries that previously produced tickets.
Show current and previous API versions without confusing users.
Restrict a partner guide while keeping public references accessible.
Ingest or generate API reference material from your source of truth.
Export content and prove how you would leave the platform later.
Explain AI assistant citations, source controls, and evaluation options.
Demonstrate audit logs, service reliability commitments, and support escalation.

This approach moves the conversation from “Does it support AI?” to “Can it solve the problems costing us time now?”

Evaluate migration reversibility

Migration pain is real, but vendor lock-in is often exaggerated when content remains portable. Favor systems that preserve content in broadly usable formats, support predictable URLs, make redirects manageable, export structured data, and avoid trapping critical logic inside proprietary templates.

The most dangerous migration is not moving pages. It is losing implicit knowledge: who owns which section, which pages are authoritative, what support links to, how versions work, and which search queries represent critical customer journeys.

Document those rules before the move. The migration can then become an opportunity to remove stale content, consolidate duplicate pages, standardize terminology, and assign owners.

A 90-day plan to reduce the docs tax

A wholesale platform migration does not need to be the first move. A focused 90-day program can establish the business case and improve the current experience regardless of the eventual vendor decision.

Days 1–30: establish the baseline

Track engineering time spent on docs operations, including interruptions and incidents.
Audit the last quarter of support tickets using the expanded deflection taxonomy.
Pull the top 50 documentation searches, zero-result queries, and ticket-linked queries.
Identify the 20 pages most frequently linked by support and the 20 most visited pages.
Inventory versions, duplicate material, broken links, stale content, and unclear ownership.
Define three baseline outcomes: reduced ticket rate for documented issues, lower engineering toil, and improved time-to-answer.

Avoid jumping immediately to a chatbot. The first deliverable should be a clear map of the current system and the cost of its failure modes.

Days 31–60: repair high-leverage gaps

Rewrite or restructure the pages behind the top documented-ticket categories.
Add query synonyms, error-code mappings, and better result ranking for important searches.
Add direct links from product errors, onboarding screens, and support macros to canonical docs.
Create owner assignments and review dates for critical documentation.
Publish clean structured references and a basic llms.txt file if public developer docs are in scope.
Pilot an AI answer layer using only approved, current sources and require citations in every answer.

Measure the result against real questions. If search and content quality improve materially, the team may find that a full platform change can be delayed or narrowed. If they do not, the evidence for migration becomes stronger.

Days 61–90: run a controlled platform decision

Shortlist two or three managed options and test them using the real-task suite. Estimate the total cost of ownership for each path over 12 to 24 months:

Current infrastructure and vendor costs
Engineering maintenance hours
Support effort tied to documented questions
Migration labor and professional services
Ongoing authoring and review time
Risk of outages or broken releases
Expected value from improved self-service and faster publishing

Do not demand perfect precision. The goal is to replace a vague debate with a decision supported by observed costs and customer-impact data.

The overlooked governance question: who owns answer quality?

Technology choices matter, but the enduring problem is governance. A new docs platform can make it easier to publish, but it cannot decide whether a changed API parameter needs an updated tutorial, whether a deprecation notice is understandable, or whether the support team is linking customers to the canonical article.

At scale, the best operating model is usually shared ownership:

Product and engineering own technical correctness and release-linked updates.
Developer experience or documentation specialists own information architecture, editorial quality, templates, and content systems.
Support owns the feedback loop from tickets, failed searches, and recurring confusion.
Security and platform teams own access controls, data boundaries, and reliability requirements for agent integrations.
Leadership owns the service-level expectation that documentation is part of the product experience.

This does not require a huge dedicated documentation organization. It requires explicit responsibilities, clear escalation paths, and metrics that make neglected docs visible before customers feel the effect.

What the r/SaaS discussion gets right

The original post is valuable because it frames documentation as capacity planning. The team did not begin with a trendy question about whether it needs an AI assistant or an MCP server. It began with an audit: where is engineering time going, and where are customers failing to self-serve?

That order is correct. AI accessibility, llms.txt, and MCP are worth considering, especially for developer-focused companies whose customers use coding agents. But they should follow the core diagnosis:

Is the content correct and current?
Can humans find and act on it?
Can support and product teams measure where self-service fails?
Is maintaining the delivery system taking too much specialized engineering time?
Would structured access create a concrete new workflow for agents?

The source post did not include substantive top-comment feedback at the time of review, so there is no meaningful community consensus to report. That absence reinforces the need to avoid copying another company’s stack blindly. The right answer depends on the company’s operational burden, content complexity, security needs, and ability to maintain a differentiated system.

Conclusion: treat docs as a leverage system

Documentation infrastructure should earn its complexity. If it takes 0.6 FTE to keep basic publishing and search functioning while customers still open tickets for answers that already exist, the system is not merely expensive—it is underperforming.

For most growing SaaS companies, the near-term priority is straightforward: measure the support and engineering burden, fix the highest-value retrieval failures, establish content ownership, and assess managed platforms against real operational tasks. Then add AI-ready formats and agent interfaces where they improve trusted access to authoritative knowledge.

The goal is not to make documentation fashionable or to deploy every new AI protocol. It is to make the correct answer easy for customers, support agents, developers, and AI tools to find—without repeatedly pulling product engineers away from the work only they can do.

FAQ

What is documentation infrastructure?

Documentation infrastructure is the set of systems and processes used to create, publish, organize, search, version, secure, measure, and maintain product documentation. It includes far more than the docs website itself.

When should a company move to a managed documentation platform?

Consider a managed platform when engineers spend meaningful time on commodity publishing operations, search is unreliable, content changes are slow, or support data shows that customers cannot find documented answers. Evaluate options using real workflows and total cost of ownership, not feature lists alone.

Will an AI chatbot reduce documentation support tickets?

It can, but only when it retrieves current, authoritative content and cites sources clearly. An AI assistant built on stale or poorly organized documentation can create inaccurate answers and more support work.

Do we need llms.txt for AI agents to use our docs?

Not necessarily. llms.txt is a useful emerging convention for curating an AI-readable map of public documentation, but it is not a substitute for stable URLs, structured references, current content, and effective search. (llmstxt.org)

Should every SaaS company build an MCP server for docs?

No. MCP is most useful when AI clients need governed, structured access to documentation, tools, or customer-specific resources. Start with excellent public docs and search; add a read-only MCP interface only when it supports a clear, valuable workflow. (modelcontextprotocol.io)

Documentation Infrastructure: How to Stop It Becoming a Hidden Engineering Tax