It was. Four years ago.

Recently a client called about their docs site. Sphinx 4 versions behind, dependencies with security vulnerabilities, relying on deprecated extensions, theme broken on new browsers, search noticeably slower.

The launch got budget. Content creation got budget. Someone even set up CI to build and deploy automatically. The team celebrated. Then moved on.

Framework upgrades, dependency updates, security patches? Nobody even brought them up. There was no line item for “keep the docs site alive.” Because it was alive. It was working fine.

Your docs site didn’t break

You just stopped keeping up with everything around it.

Every dependency you don’t update becomes a risk. Every framework version you skip makes the next upgrade harder. None of it is urgent on any given day. All of it is urgent four years later.

The decay is invisible. The site loads. The search works. The pages render. Until one day they don’t. Or they do, just slower, just slightly broken, just enough for users to notice before you do.

The cost equation

Keeping a docs site maintained is routine work. Not always simple, but manageable if you stay current. It just never wins against everything else on your roadmap. A few hours a quarter to update dependencies. A CI check for broken links. An annual framework upgrade before you fall too far behind. Call it 20 to 30 hours a year. Maybe $3 to 5K if you’re paying someone.

That client's docs were broken for at least three months before anyone flagged it. The fix took another six weeks. Four and a half months of slow search and a theme that looked off on half the browsers visiting it. All that time, the docs were quietly telling users you don't maintain your tools.

Your docs site is a production system

We all understand this for apps. Nobody ships a production app and walks away for four years. There are monitoring tools, dependency bots, upgrade cycles.

Docs sites get none of that. They get launched and forgotten. Then someone calls you four years later wondering why everything is broken.

It has users, dependencies, and security surface area. It deserves the same care.

That client’s site is fixed now. They’re on a maintenance plan. The kind of work that never makes headlines but means nobody has to make that call again.

Most documentation disasters come from organic growth. One team adds a page here, another over there. Nobody’s thinking about the whole. Structure only becomes a concern after hundreds of pages exist, when nothing is easy to find or truly useful.

The pattern is always the same: content first, then more content, then nobody can find anything. Then someone finally asks “should we reorganize this?” when reorganization means touching 300 pages and breaking every bookmark and search result.

Strategy → Structure → Content.

Not Content → More Content → Chaos.

What documentation strategy actually means

Strategy doesn’t mean a 40-page plan. It means answering a few critical questions before anyone writes a word:

Who are you writing for?

Not “developers.” That’s too vague. Define specific personas in specific situations. A developer integrating your API under deadline pressure needs different content than an enterprise architect evaluating your security model. Pick a primary audience. Acknowledge the others exist, but know who you’re optimizing for.

What job is each piece of documentation doing?

Documentation serves different purposes:

• Teaching a concept through example (tutorial)

• Solving a specific problem (how-to guide)

• Looking up syntax (reference)

• Understanding why something works this way (explanation)

These aren’t interchangeable. A reference doc won’t teach a beginner. A tutorial won’t help someone troubleshooting at 2am. Your strategy needs to decide which jobs matter most for your product and your users, then commit to doing those jobs well.

What’s the minimum content that unlocks the product?

You don’t need comprehensive API docs on day one. You don’t need advanced guides for features nobody’s using yet. You need whatever removes the biggest obstacle between a new user and their first success.

Everything else can wait. The question isn’t “what should we document eventually?” It’s “what’s blocking someone right now?”

What should each page cover?

Once you know which content types you need, define what makes each one complete. Tutorials should list prerequisites up front and guide users to a working example. API references need request examples, response formats, and error codes. How-to guides should state the outcome at the start and show the steps clearly. Explanations need context on why things work the way they do.

This is where templates help. They ensure consistency and completeness across your documentation. But templates only work after you’ve defined your strategy. Without clarity on what each page type requires, templates just give you consistently incomplete content that raises more questions than it answers.

The early content trap

In practice, you can ship some early content while doing this thinking. In fact, you should. But those quick wins should not define the strategy.

You've seen this before: you ship a tutorial because five users asked for it. Then a troubleshooting doc because support is overwhelmed. Then someone adds an FAQ. Then best practices. Each one makes sense in isolation. None of them were planned together. Six months later, you have 50 pages organized by the order they were written, not the order anyone needs them.

A strategic early win looks different. You know it’s one piece of a larger system. You know where it lives. You know what comes before and after it. Even if you haven’t written those other pieces yet, you’ve left room for them.

This is the difference between “we need a tutorial, someone write it” and “we need a tutorial that assumes zero prior knowledge, gets someone to a working integration in under 10 minutes, and hands them off to either the API reference or advanced tutorials depending on what they want to do next.”

Same deliverable. Completely different foundation.

What changes when you do this right

Writing gets faster. You’re not reinventing structure with every new page or second-guessing where something belongs.

Maintenance gets easier. When something changes in your product, you know exactly which docs need updates because you understand how the pieces relate.

Users find what they need. Not because your search is amazing, but because the structure matches how they think about problems.

Teams can contribute confidently. A new PM can add content because the system makes it obvious where things go.

None of this happens if you start with content and hope structure emerges. Structure rarely emerges on its own. Chaos does.

How to start

You don’t need perfect answers to those strategy questions. You need good enough answers and permission to revisit them.

Spend a week, maybe two. Talk to five users about what they’re trying to do. Look at your support tickets and see what’s actually confusing people. Sketch out the 10-15 core topics your documentation needs to cover and how they connect.

What works for me: start by mapping navigation flows for each persona. Where does a junior developer enter your documentation? What’s their path to first success? What do they need next? Where does a senior architect start, and what questions do they need answered to evaluate your product? Sketch these journeys. Where each audience type enters, what they read, where they go when they’re stuck.

Example navigation flows for two different personas. Use it to identify key content and paths.

These flows reveal what content you actually need, not just what seems logical to document. Also, they will help you define your structure.

Structure isn’t about folders. It’s about reflecting how users think about your product. If your users think in terms of workflows, organize by workflow. If they think in terms of features, organize by feature. Don’t organize by how your engineering team structured the codebase. Nobody outside your company thinks that way.

Then create a grid in a spreadsheet. One row per page or section you think you’ll need based on the previous exercise.

Columns for:

• Module / page title

• Persona: who is this for?

• Content type: tutorial, reference, how-to, explanation

• Priority: must-have for launch, nice-to-have, future

• Description: Brief description of what the page covers, required subheadings.

The grid forces you to think about the whole system at once instead of page by page. You’ll see gaps (”wait, we have five reference docs but no how-tos?”) and redundancies (”these three pages are basically the same thing”).

What I’ve found useful: identify your action-oriented content first (tutorials and how-to guides), then build supporting reference and explanation docs around them. These supporting docs can be referenced from multiple guides, so you’re not repeating the same API details or concepts in every tutorial. This keeps guides focused on the task while providing depth for users who need it.

Together, the flows and the grid become your roadmap. When someone asks “should we document X?” you can see where it fits, or doesn’t. When priorities shift, you adjust the plan, not 47 individual pages.

Then start writing. But you’re writing into a framework now, not into a void.

Strategy doesn’t slow you down. It’s what makes fast sustainable.

Planning your documentation strategy?

If you’re staring at documentation chaos or launching something new and want to avoid building problems into your foundation, we can help.

We work with teams to design content architecture that scales: mapping personas, defining structure, and creating the roadmap before anyone writes a word.

Your content stays in their system. Your build process depends on their infrastructure. Your ability to move depends on their export tool, which barely works.

Docs-as-code flips this. Content is markdown in Git. You own the build process. You can host anywhere. Switch tools without losing content.

This isn’t anti-SaaS (there are docs-as-code friendly platforms out there). It’s about keeping ownership of your content so it doesn’t become leverage for someone else.

Your docs are a business asset. Treat them like one.

P.S. I’m back on Substack with a weekly note on technical writing, docs-as-code, and automation. If you’re not interested, you can unsubscribe anytime.

Here are strategies for catching documentation issues earlier. Ordered by impact.

Pre-publication review

Get feedback before documentation goes live. Get up to three reviewers with different perspectives: a subject matter expert (catches technical errors), a technical writer (checks clarity and style), and someone without context (tests if it actually works).

You don’t need all three. Even one reviewer helps. The key: tell them what to focus on. “Check technical accuracy” is clearer than “review this.”

Not everything needs the same level of review. A new tutorial deserves a thorough look. A typo fix in a reference page? Quick scan is fine.

This breaks down when deadlines are tight or reviewers are unavailable. But preventing issues is always cheaper than fixing them after users complain. Schedule review time upfront because teams always forget it in estimates.

Strategy 2: Monitor communication channels

Watch where users discuss your documentation. Support tickets, forums, GitHub issues, social media, internal Slack. Look for patterns:

“The docs don’t explain X.” “I couldn’t figure out how to Y.” “Spent 2 hours on Z before...”

When you spot problems, create documentation issues from them. Track them and fix them.

This should be your baseline. Users talk about your documentation whether you listen or not. The feedback is unfiltered. They’re not trying to be nice, they’re venting or asking for help, which makes it valuable.

On-page feedback widget

Put a feedback mechanism directly on the documentation page. Users click a button, highlight a section, and say what’s wrong. Anonymous, no account needed, feedback routes to your issue tracker.

Tools like PushFeedback let users annotate specific sections visually. They see the issue, highlight it, leave a comment. You get a screenshot with context.

If you have an AI chatbot on your docs, review what users ask it. Questions the chatbot couldn’t answer point to missing documentation. Questions asked repeatedly point to unclear documentation. If 50 users ask about webhook security in a month, that’s a signal to write that guide.

The alternative is linking to GitHub issues. Works for developer-heavy audiences, costs nothing. But most users won’t leave the page, create an account, and give public feedback.

User testing sessions

Watch someone use your documentation in real-time. Don’t explain anything. Don’t help them. Just watch where they pause, re-read, or give up.

This works well for complex workflows, multi-step tutorials, and onboarding documentation. Simple reference docs have nothing to “test.”

We helped Finboot run an “Escape Room” using their docs. The company split into teams and tried to solve a puzzle by following documentation: sending blockchain transactions in the correct sequence. Everyone experienced the pain points firsthand. Inconsistencies, ambiguous instructions, missing steps. The whole company became motivated to fix it.

Intensive to set up, but it makes abstract documentation problems concrete.

User interviews

Schedule time with users who recently used your docs. Ask what worked and where they got stuck.

Interviews reveal things other methods miss. The specific sentence that confused them. The assumption they made that broke everything. But they don’t scale. External users at scale are hard to schedule, and anonymous user bases can’t be reached.

Best for internal documentation and B2B products where you know your users.

Surveys

Ask broad questions. “How helpful is our documentation?” “What topics are missing?”

Surveys give you trends and general sentiment. They don’t give you actionable issues. Users don’t remember which specific guide confused them two weeks ago.

Good for measuring documentation health over time. Not for finding specific problems.

Where to start

Most teams start with pre-publication review and monitoring. Those two cover the most ground with the least effort.

Then add other strategies based on your constraints: budget, team size, user base, and how much traffic your docs get.

Your documentation improves when you stop waiting for complaints and start actively seeking problems.

The fix isn’t writing better docs. It’s treating docs like code: version-controlled, automatically built, and tested in CI.

What this workshop covers

I recorded this workshop for PyCon APAC 2020. It walks through a full docs-as-code setup:

• GitHub to host docs next to source code

• reStructuredText to write in plain text instead of Word or Confluence

• Sphinx to generate a documentation site from those files

• ReadTheDocs to build and publish automatically on every commit

• Vale to lint your docs the same way you lint your code (style, consistency, broken links)

By the end, you have a pipeline: write in plain text, commit to Git, site builds and deploys automatically. No manual publishing steps.

Why bother

Docs live with code. When a developer changes an API, the docs are right there in the same repository. Updating them becomes part of the normal workflow, not a separate task someone forgets about.

Testing catches issues before users do. Vale flags inconsistent terminology, passive voice, broken links. Same CI pipeline that runs your unit tests.

And you own everything. Plain text files in Git. No vendor lock-in, no proprietary formats, no export headaches.

Go deeper

The Write the Docs community is the best place to learn from practitioners who actually do this. Worth joining if you’re serious about docs-as-code.

“Can we support localized docs?”

Technically? Yes. Should you? Maybe not.

Teams underestimate what it takes to maintain translations. Documentation changes constantly. Translations need to keep up. Most teams can’t.

Mistake 1: Translating without a goal

Google Analytics shows traffic from Japan. Someone suggests translating to Japanse. Six months later, the Italian docs are outdated and nobody maintains them.

Traffic from a country doesn’t mean you need docs in that language. English might be fine for technical audiences.

Better reason to translate: You’re entering a specific market next quarter. You have native speakers on the team who will maintain it. You’ve validated that language blocks users from adopting your product.

Don’t translate “just in case.” Translate when you have a specific goal and resources to maintain it.

Mistake 2: Translating everything at once

You decide to support Italian. You translate all 200 pages.

Three months later, the English docs evolved. The Italian docs are behind. Users hit outdated instructions. Support tickets arrive in Italian. Nobody on support speaks Italian.

Translation isn’t a one-time project. It’s ongoing maintenance.

Start smaller: Translate the 20% that delivers 80% of the value. Installation guides. Quickstart. Core concepts. Leave advanced features and edge cases untranslated.

Users can handle some pages in English if the critical path is in their language.

Mistake 3: No version control strategy

You spin up separate documentation projects per language. English docs move fast. German docs lag behind. Users hit German tutorials that reference features from version 1.0. The current version is 3.0.

Outdated documentation is worse than no documentation.

You need a policy for managing translation lag. Three options:

• Content availability: Keep translated sections that haven’t changed. Show new content in English until it’s translated. Gradually update the untranslated parts. Users see mostly German with some English sections clearly marked as “not yet translated.” Works for most technical documentation. Users can handle mixed languages if the critical path is translated.

• Language consistency: Each language has its own version. German might be on v2.0 while English is on v3.0. Tag outdated docs with warnings. Link to the latest English version. Works when you want each language to feel complete, even if behind.

• Perfect sync: Wait to release docs until all translations are ready. Medical devices, government contracts, financial services often legally require this. Documentation and product ship together, all languages synchronized. This works when you have no choice. Otherwise, documentation becomes a bottleneck.

Mistake 4: Ignoring SEO

You launch Portuguese docs. Google sees duplicate content (same structure, different language). Your search rankings drop.

Or worse: you don’t configure SEO properly. Users in Spain search for your product in Spanish. Google shows them your English docs. They never find the Spanish version.

Fix it:

• Use separate URLs per language (`docs.yoursite.com/es/`)

• add hreflang tags (tells Google which language each page is in)

• Generate complete sitemaps including all languages

• For untranslated pages, add <meta name=”robots” content=”noindex”> so they don’t compete with English versions.

Make translated docs discoverable. Otherwise, why translate at all?

Mistake 5: No consistency between translators

Two people translate your docs to Spanish. One translates “Software Development Kit” as “Kit de desarrollo.” The other uses “Herramientas de desarrollo.”

Both are valid. But inconsistency confuses users. They think these are two different things.

Create a glossary:

Map domain-specific terms to preferred translations:

• Software Development Kit → Kit de desarrollo

• API → API (don’t translate)

• Webhook → Webhook (don’t translate)

• Configuration → Configuración

Share it with translators. Make it part of the review process.

Technical terms often stay in English. That’s fine. Consistency matters more than translating everything.

When translation makes sense

You should translate when:

• Regulation requires it (medical devices, government contracts, financial services in certain countries)

• You’re entering a specific non-English market and English blocks a significant portion of users.

• You have budget for ongoing translation (not just initial translation)

• You have native speakers maintaining translations

You probably shouldn’t translate when:

• Your users are developers (most read English technical docs)

• You’re an early-stage product (docs change too fast)

• You can’t commit to maintaining translations

• You’re translating to “be international” without specific goals

Start with one language

Don’t launch with five languages. Pick one. The market you’re targeting. The language your team speaks natively.

Translate 20% of the docs. The critical path. See if it works. Measure if it helps.

If it does, expand. If not, you didn’t waste effort translating everything.

Technical setup

Use internationalization (i18n) tooling built for documentation.

The approach:

• Choose a primary language (usually English)

• Extract translatable strings into Portable Object Template (POT) files

• Translators work with PO files (only the strings, not the full docs)

• When original content changes, only changed strings need retranslation

Automate extraction. Every time docs update, regenerate the POT files. Translators see exactly what changed.

Tools like Transifex or Lokalise show what needs translation in a friendly UI. Team members can translate collaboratively. Built-in review process catches inconsistencies.

This is better than asking translators to edit markdown files directly.

The real cost

Translation isn’t just the initial cost. It’s ongoing maintenance.

Every docs update needs translation. Every new feature. Every bug fix that affects documentation. Every restructure.

If you ship docs in three languages, every change multiplies by three. If you can’t handle that, don’t translate yet.

Focus on quality in one language first. Then expand when you have the resources to maintain it.