It breaks down the moment someone has to ship something. To deploy a new service, an engineer has to call the auth service, get a token, call the payments service, handle the webhook, and wire it into the deployment pipeline.

No single team’s docs cover the full sequence. The pieces are documented, but the connection between them isn’t.

What gets lost between docs

The integration patterns that connect one team’s product to another’s live in the heads of senior engineers. They learned them from pairing, from code review, from mistakes shipped to production. The knowledge is there, but it’s never written down because no team owns it.

Per-team docs don’t fix this. The auth team can’t write about how their service gets used inside the payments flow without overstepping, and the payments team can’t document the auth integration without speaking for another team. So nobody does.

The unwritten rules and best practices stay unwritten for the same reason. “Always wrap external calls in the retry helper.” Nobody owns that either, so it lives in code review comments and gets passed on by correction, not documentation.

Codelabs cover the seams

A codelab is a step-by-step exercise that walks an engineer through building something real. A starter repository, a scenario, the steps to get from empty to working, and a reference implementation to compare against.

What makes them work as internal docs is that they’re scenario-first, not product-first. A codelab pulls in whichever services the scenario requires.

A codelab on “build a service that handles webhook events from our payment provider” uses three or four internal products in one exercise. By the end, the engineer knows not just what each product does, but how they fit together in the way your company actually builds.

Where to start

If your engineers are slow to ramp up and each team’s docs look fine, the gap is probably between them. This is where a codelab earns its keep.

Pick the cross-team scenario new hires hit first, the one that usually means three weeks of asking around, and build a codelab that walks through it end to end. Keep it current as the services change.

You don’t need many. A handful covering the workflows people actually run does most of the work. The goal isn’t a codelab for everything, it’s getting people through the paths they’ll actually walk.

It rarely goes that way. Plans built on assumptions break the moment real content meets the new platform.

That’s why we don’t quote large migrations up front. We pilot first.

Why a pilot first

Planning a full migration up front assumes you can predict what the work will look like. You can’t. Not at this scale, not with content this varied.

A pilot surfaces what the plan can’t see: the issues that only appear once real content meets the real platform. Some look like minor rendering bugs. Others reshape the whole approach.

So we migrate one slice end to end. That slice might be one product in a multi-product migration, one section of a large doc set, or a single content type. The shape of the project decides the unit.

That’s enough to know what the next slice will cost, what the rest will cost, and where the work is most likely to slip.

Picking the right pilot

The slice you pick decides whether the pilot is worth running. The temptation is to start with the easiest one: smallest content, simplest structure, friendliest team. Those pilots ship smoothly and teach you nothing about the rest. Pick something closer to the average instead.

Give the pilot a deadline too. Without one, it stops being a pilot and turns into the project itself, and you lose the reason you ran it in the first place.

And when leadership wants the full scope committed before any work starts, plan with the pilot in mind. Run one slice through the full workflow first, then narrow the estimate as the project takes shape.

Evidence over estimates

Most migration projects fail in scope-setting, not in execution. The pilot is how we set scope honestly. The estimate we give for the full project is the one we earned by doing part of it.

Ship one, then scale. You’ll learn more from one migrated slice than from any plan.

It was working fine. Four years ago.

A client called recently about their docs site. Sphinx four versions behind, dependencies with known security vulnerabilities, deprecated extensions holding the build together, a theme broken on current browsers, and search that had grown 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 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, and 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. The problem is that it never wins against everything else on the roadmap.

The actual cost is modest. 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.

Compare that to what neglect cost this client. Their docs were broken for at least three months before anyone flagged it, and 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 that this company doesn’t maintain its 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. A docs site has users, dependencies, and security surface area too. It deserves the same care.

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, and 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 adds one over there, and nobody is thinking about the whole. Structure only becomes a concern after hundreds of pages exist, by which point nothing is easy to find.

The pattern is always the same: content, 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. You should, even. But those quick wins shouldn’t define the strategy.

You’ve seen how this goes. 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, and what comes before and after it. Even if you haven’t written those other pieces yet, you’ve left room for them.

It’s 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

The writing gets faster, because you’re not reinventing structure with every new page or second-guessing where something belongs.

Maintenance gets easier, because when the product changes you know exactly which docs need updating and 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. A

nd new contributors can add content confidently, 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 to see what’s actually confusing people. Then sketch the 10 to 15 core topics your documentation needs to cover and how they connect.

The approach I use is to map navigation flows for each persona first. Where does a junior developer enter your documentation? What’s their path to first success, and 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 enters, what they read, and 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, and they give you your structure.

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

Then build a grid in a spreadsheet, one row per page or section you think you’ll need. Give it columns for the page title, the persona it serves, the content type (tutorial, reference, how-to, explanation), the priority (must-have for launch, nice-to-have, future), and a short description of what the page covers.

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 spot gaps (”wait, we have five reference docs but no how-tos?”) and redundancies (”these three pages are basically the same thing”).

One thing I’ve found useful: identify your action-oriented content first, the tutorials and how-to guides, then build reference and explanation docs around them. Those supporting docs can be referenced from multiple guides, so you’re not repeating the same API details in every tutorial. The guides stay focused on the task while the depth lives somewhere reusable.

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 instead of 47 individual pages.

Then you start writing. But now you’re writing into a framework, 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. Your content is markdown in Git, you own the build process, and you can host it anywhere. Switching tools no longer means losing content.

This isn’t anti-SaaS. There are plenty of 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. Not interested? You can unsubscribe anytime.

Here are strategies for catching documentation issues earlier, ordered roughly by impact.

Pre-publication review

Get feedback before documentation goes live. Aim for up to three reviewers with different perspectives: a subject matter expert to catch technical errors, a technical writer to check clarity and style, and someone without context to test whether it actually works.

You don’t need all three. Even one helps, as long as you tell them what to focus on. “Check technical accuracy” gets you further than “review this.”

Also, not everything needs the same level of review. A new tutorial deserves a thorough look. A typo fix in a reference page just needs a quick scan.

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

Monitor communication channels

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

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

When you spot one, turn it into a documentation issue, track it, and fix it.

This should be your baseline. Users talk about your documentation whether you listen or not, and the feedback is unfiltered. They’re not trying to be nice, they’re venting or asking for help, which is exactly what 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. No account needed, and the feedback routes straight to your issue tracker.

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

The lighter-weight alternative is linking to GitHub issues. It works for developer-heavy audiences and 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. Simple reference docs have nothing to “test.”

We once helped Finboot run an “escape room” using their docs. The company split into teams and tried to solve a puzzle by following the documentation, sending blockchain transactions in the correct sequence. Everyone hit the pain points firsthand: inconsistencies, ambiguous instructions, missing steps. The whole company came out motivated to fix it.

It’s intensive to set up, but it makes abstract documentation problems concrete.

User interviews

Schedule time with users who recently used your docs and 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.

The catch is they don’t scale. External users are hard to schedule at volume, and anonymous user bases can’t be reached at all. Best for internal documentation and B2B products where you know who your users are.

Surveys

Ask broad questions. “How helpful is our documentation?” “What topics are missing?” Surveys give you trends and general sentiment, but not 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 channel monitoring. Those two cover the most ground for the least effort. Add the others 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 looking for 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, and the translations have to keep up. Most teams can’t.

Mistake 1: Translating without a goal

Google Analytics shows traffic from Japan, someone suggests translating to Japanese, and 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 is often fine for technical audiences.

Better reason to translate: ou're entering a specific market next quarter, you have native speakers on the team who will maintain it, or you've validated that the language barrier is actually blocking users from adopting your product.

Don't translate "just in case." Translate when you have a specific goal and the resources to maintain it.

Mistake 2: Translating everything at once

You decide to support Italian, so you translate all 200 pages. Three months later the English docs have moved on, the Italian docs are behind, and users hit outdated instructions. Support tickets start arriving in Italian, and nobody on the support team speaks it.

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

Start smaller: Translate the 20% that delivers 80% of the value: installation guides, the quickstart, core concepts. Leave advanced features and edge cases in English. Users can handle some pages in English as long as the critical path is in their language.

Mistake 3: No version control strategy

You spin up separate documentation projects per language. English moves fast, German lags behind, and users hit German tutorials that reference features from version 1.0 when the current version is 3.0. Outdated documentation is worse than no documentation.

You need a policy for managing translation lag. There are three common approaches.

• Content availability: Keep the translated sections that haven’t changed, show new content in English until it’s translated, and gradually update the rest. Users see mostly German with some English sections clearly marked “not yet translated.” This works for most technical documentation.

• Language consistency: Each language has its own complete version. German might be on v2.0 while English is on v3.0. You tag the outdated docs with a warning and link to the latest English version. This works when you want each language to feel complete, even if it’s behind.

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

Mistake 4: Ignoring SEO

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

Or worse, you don’t configure SEO at all: users in Spain search for your product in Spanish, Google shows them your English docs, and 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 into Spanish. One renders “Software Development Kit” as “Kit de desarrollo,” the other uses “Herramientas de desarrollo.” Both are valid, but the inconsistency confuses users into thinking these are two different things.

Create a glossary that maps 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 your translators and make it part of the review process. Technical terms often stay in English, and 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, or the language your team speaks natively. Translate 20% of the docs, the critical path, and see whether it helps. If it does, expand. If not, you haven’t wasted effort translating everything.

Technical setup

Use internationalization (i18n) tooling built for documentation. The basic 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 the extraction so that every time the docs update, the POT files regenerate and translators see exactly what changed.

Tools like Transifex or Lokalise show what needs translation in a friendly UI, let team members translate collaboratively, and build in a review process that catches inconsistencies.

It beats 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 touches the docs, 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.