The Docs Problem, Again

Every engineering team reaches a point where the knowledge problem becomes acute. The codebase has grown. The original team has dispersed. New engineers spend their first weeks lost, not because they're not capable, but because the information they need is scattered across Notion pages, Slack threads, Confluence wikis, and the heads of the three people who were there in the beginning.

The answer, everyone keeps deciding, is a better portal.

The Internal Developer Portal (IDP) category has exploded over the last few years. Backstage from Spotify is the most visible example, but there are dozens of commercial alternatives. The pitch is compelling: a single pane of glass for everything an engineer needs: service catalog, API docs, runbooks, onboarding guides, deployment tooling.

We've watched teams adopt these portals closely. Some of them work. Most of them don't. And they fail for a surprisingly consistent reason.

Why Portals Fail

Here's the pattern we see repeatedly:

  1. A team is frustrated by documentation sprawl
  2. They adopt a portal and migrate everything into it
  3. Adoption is high for the first few months
  4. The portal gradually becomes another place where information goes to stale
  5. Engineers stop trusting it and go back to asking on Slack

The portal didn't solve the problem. It just moved it.

The underlying issue is that portals treat documentation as a retrieval problem when it's actually a maintenance problem. You can make it easier to find information. But if no one is responsible for keeping that information accurate, finding stale information faster doesn't help.

The teams that solve this understand something the failed teams don't: a portal is infrastructure, not content. The infrastructure can be excellent. Without a content strategy, it's a beautiful empty building.

What Actually Works

Tie documentation to code

The best documentation is as close to the code it describes as possible. README files. Inline comments that explain why, not what. API documentation generated from code annotations.

When documentation lives in the same repository as the code, it gets reviewed in the same pull request. It gets updated when the code changes. It has a clear owner.

When documentation lives in a separate wiki, it drifts. No one's PR checklist includes "update Confluence." The code moves forward. The docs fall behind.

Distinguish between reference and learning

Reference documentation (API specs, configuration options, architecture diagrams) and learning content (tutorials, onboarding paths, how-tos) serve completely different purposes and degrade at different rates.

Reference docs need to be accurate. They're used by engineers who already know roughly what they're looking for.

Learning content needs to be complete. It's used by engineers who are lost. A slightly outdated tutorial that walks you through the full flow is more useful than a perfectly accurate reference that assumes you already understand the flow.

Most portals treat both as the same content type. They're not.

Make staleness visible

The Confluence curse is that you can't tell whether a page was last updated in 2024 or 2019. Both look the same.

Good portals surface age prominently. They route to the page owner when content reaches a certain age. They give engineers an easy way to flag content as outdated without having to fix it themselves.

Making the maintenance problem visible doesn't solve it, but it's a prerequisite for solving it.

Use labs for the hard stuff

Some knowledge doesn't transfer through reading. Setting up a local development environment. Running your first deployment. Understanding how the observability stack fits together.

For this kind of procedural knowledge, interactive labs outperform documentation every time. The engineer doesn't just read about the deployment process. They do it in a real environment, with validation that tells them when they've succeeded.

This is why we built Stepwik's portal integration: so that the operational knowledge that lives in your IDP isn't just readable, but learnable.

The Portals Worth Paying Attention To

The most successful IDP implementations we've seen share a few traits:

  • A dedicated person (or small team) who owns content quality, not just platform maintenance
  • A clear split between code-adjacent reference docs and standalone learning content
  • Automated staleness detection with a defined review cadence
  • Interactive labs for any content that involves a sequence of terminal commands or configuration steps
  • An easy path for engineers to contribute without being content experts

None of this requires a sophisticated portal. It requires a strategy.

The Honest Assessment

Internal developer portals are worth building when teams approach them with the right expectations. They're not a solution to documentation rot. They're an investment in the infrastructure that makes documentation maintainable.

Get the strategy right, pair it with interactive learning where it matters, and a good portal becomes one of the most valuable things your engineering organization can build.

Get the strategy wrong, and you've added a new place for information to decay.

The difference is entirely in how you approach it and whether you're willing to treat content as a product, not an afterthought.