Building an Internal Developer Portal with AI Documentation

Most internal developer portals die the same way: the docs go stale within three months of launch. A new service gets added, the golden path changes, the catalog entry stays frozen in last quarter's reality, and engineers quietly stop trusting the portal. The pattern is consistent enough across companies that it's worth naming — the portal becomes a beautiful front door to wrong information.

The fix isn't more documentation. It's documentation that regenerates from the source of truth — your code, your infra, your runbooks — every time something changes. That's the wedge where AI documentation fits inside an IDP, and it's what platform engineering teams should be building toward in 2026.

Why Most IDPs Underdeliver

An internal developer portal (IDP) is the backstage area where engineers find services, environments, runbooks, ownership data, and self-service actions. The promise is faster onboarding, less cognitive load, and consistent golden paths. The reality, in most companies that rolled one out between 2022 and 2025, is something closer to a static wiki with a search bar.

Three failure modes show up repeatedly:

• Drift between code and catalog. A new microservice gets deployed. The IDP doesn't know about it. Six months later, no one can answer whether the service is even supported.
• Ownership rot. On-call rotations change, teams rename, people leave. The portal still shows "team-platform@" as the owner of services they haven't touched in two years.
• Runbook decay. The incident response runbook describes a service that has been rewritten twice. Nobody updates it because the original author left.

The common thread: documentation that lives separately from the code it describes. An IDP can't fix this by being a better frontend. The portal needs to be wired into the systems engineers trust — the repo, the CI pipeline, the incident tracker — so that documentation is a derived artifact, not a hand-maintained one.

What AI Documentation Actually Means Here

When platform engineers say "AI documentation" in 2026, they don't mean a chatbot that summarizes a README on demand. They mean a pipeline that:

1. Reads code, IaC, configs, and existing docs from the connected sources.
2. Generates structured artifacts — READMEs, API references, architecture diagrams, onboarding guides, golden-path templates.
3. Re-runs automatically when those sources change, via webhooks.
4. Surfaces the artifacts inside the IDP, indexed and searchable.

This is the same pattern DevOps applied to deployments: treat the doc as code, but let the platform generate it instead of asking humans to write it by hand. Done well, the IDP becomes a real-time view of what the engineering org actually shipped, not what someone remembers it shipped.

The Architecture: IDP + Doc Engine

A workable architecture has four layers. Platform teams that have shipped this in production tend to converge on something close to the following.

Layer 1: Sources of Truth

These are the systems the documentation engine reads from:

• GitHub or GitLab repositories for code and IaC.
• Terraform / Pulumi state for environment topology.
• Service catalogs (Backstage, Port, custom) for service metadata.
• Incident trackers (PagerDuty, incident.io) for ownership and on-call data.
• CI pipelines for build, test, and deploy artifacts.

The critical decision is what counts as authoritative. A common mistake is treating READMEs as authoritative — they aren't, the code is. READMEs become generated output, not input.

Layer 2: The Documentation Pipeline

This is where AI does its work. For each service or component, the pipeline:

• Indexes the repo, dependency manifests, IaC, and any existing structured metadata.
• Generates a doc bundle: README, API reference (from route handlers or OpenAPI specs), architecture summary (from module boundaries and dependencies), onboarding checklist.
• Stores the bundle in a versioned location — usually a docs repo or an S3 bucket with a content-addressable path.

The generation step can use a mix of heuristics and LLMs. Heuristics work well for anything derivable from structure: API routes from Express handlers, dependency graphs from package manifests, environment variables from IaC. LLMs fill the gap for prose summaries, onboarding guides, and architecture narratives.

Layer 3: Webhooks and Sync

The doc pipeline must re-run when source changes. This is where most internal builds fall down — they treat generation as a one-shot task. In practice you need:

• GitHub webhooks on push, PR merge, and tag.
• Catalog webhooks for service registration and ownership changes.
• Scheduled refresh for anything that doesn't have a clean event source — ownership rosters, on-call rotations, dependency vulnerabilities.

The webhooks aren't optional. Without them, you're back to stale documentation within a quarter.

Layer 4: IDP Frontend

The IDP — Backstage, Port, a custom Next.js app, whatever — reads the doc bundle and surfaces it. The portal isn't generating anything; it's a viewer with search, navigation, and self-service actions layered on top.

# Example: a generated service record exposed to the IDP
service:
  id: payments-svc
  name: Payments Service
  owner: payments-platform
  tier: 1
  repo: github.com/acme/payments-svc
  runtime: go-1.22
  dependencies:
    - postgres
    - kafka
    - stripe-api
  docs:
    readme: /docs/payments-svc/v142.md
    api: /docs/payments-svc/v142.openapi.json
    architecture: /docs/payments-svc/v142.arch.md
    onboarding: /docs/payments-svc/v142.onboarding.md
  generated_at: 2026-01-14T09:22:11Z

Note the v142 in the doc paths. Versioning is how you avoid the next failure mode: an engineer reading a doc that's three weeks out of date because a regeneration silently overwrote the previous one.

Platform Engineering: What to Build vs. Buy

Platform teams building this in 2026 tend to split the work along a clean line.

Build the wiring, buy the generator

The high-leverage work — webhooks, versioned storage, IDP integration, ownership resolution, freshness signals — is custom to your org and worth building in-house. The generator, which is where AI does the heavy lifting, is generic enough that it's almost always faster to adopt a tool than to build one.

This is where tools like DocPilot slot in. DocPilot connects to GitHub, scans the code, generates the doc bundle, and re-runs on every push via webhooks. The platform team's job becomes the part that's actually org-specific: wiring the output into your IDP, mapping ownership, defining what "tier 1" means, and exposing the right self-service actions.

What to instrument first

If you're starting from a zero-base IDP, don't try to document everything. Pick the surface that hurts most when it's wrong:

• Service catalog entries with wrong owners.
• Onboarding guides for the top 5 most-provisioned services.
• API references for the services other teams integrate with most.
• Incident runbooks for tier-1 services.

Instrumenting these first is also how you get organizational buy-in. The first time an on-call engineer finds a freshly regenerated runbook during an incident, the rest of the org stops questioning why the platform team is building this.

A Concrete Example: Documenting a New Service

Walk through what happens when a team creates a new service in a setup like this.

1. The team pushes the repo to GitHub. The repo contains a standard template: Dockerfile, terraform/, package.json (or equivalent), and a service.yaml manifest declaring ownership and tier.
2. GitHub fires a webhook. The doc pipeline indexes the repo.
3. Within a few minutes, a doc bundle is generated: README, API reference, architecture summary, onboarding checklist. The bundle is committed to a docs repo as services/<service-id>/v1.md.
4. The IDP picks up the new entry, the service appears in the catalog with docs linked, and the owning team gets a notification to review.
5. On every subsequent PR merge, the docs refresh. A diff in the docs shows up in the same PR review.

The last point is the one that compounds. Engineers stop thinking about documentation as a separate task. It comes with the change, like tests do in a mature CI setup.

Measuring Whether It's Working

A portal without metrics is a portal nobody can defend at budget time. Four numbers tend to separate working IDPs from the dead ones:

Metric	What it tells you	Target direction
Doc freshness (median age)	How often regeneration is actually happening	Lower
Catalog coverage (% of services with current docs)	Whether new services are being captured	Higher
Time-to-first-PR for new hires	Whether onboarding docs are usable	Lower
Portal search → action conversion	Whether engineers trust it enough to act on it	Higher

If freshness stays above two weeks for tier-1 services, the webhook chain has a hole. If catalog coverage stalls below 80%, the service registration flow isn't capturing new repos. These metrics turn the IDP from a deliverable into a system with feedback.

Common Pitfalls

Three failure patterns show up often enough to call out:

• Letting humans edit generated docs. If engineers start hand-editing the README the AI wrote, the next regeneration undoes their changes and trust collapses. Generated docs should be regenerated from sources, period. Human edits go in a separate "additions" layer or in the code itself.
• Skipping versioning. Pinning docs to a version means engineers can compare, audit, and roll back. Without it, a bad regeneration silently breaks something engineers were relying on.
• Treating the IDP as a project, not a product. Portals that ship once and are "done" decay. Assign a small team to own it as a product — measure usage, talk to internal users, prioritize changes.

Where to Start

The shortest path to a working IDP with AI documentation in 2026 is narrower than it sounds:

1. Pick one source of truth (GitHub is usually the highest-leverage one).
2. Stand up a doc generator that reads from it and writes versioned artifacts.
3. Wire webhooks so generation is automatic.
4. Surface the artifacts in your IDP, starting with service catalog entries and onboarding guides.
5. Measure freshness and coverage, and tighten the loop.

The portal doesn't need to be beautiful on day one. It needs to be accurate, and it needs to stay accurate without a human maintaining it. That's the bar AI documentation clears — and the bar an internal developer portal has to clear to actually be worth the build.

---

If the doc pipeline is the piece you've been putting off because the build cost looked high, that's the part worth looking at first. DocPilot plugs into GitHub, generates READMEs, API references, architecture summaries, and onboarding docs from the actual code, and keeps them in sync via webhooks on every push. The platform team wires the output into the IDP; the generator handles the part that used to take a quarter to get right. Free tier is available if you want to try it on one repo before committing the org.