I've watched three teams build "platforms" in the last five years. Every single one optimized for discoverability and consistency while quietly making it harder to ship.
The pattern: you spend months building a beautiful portal. Docs are centralized, golden paths are documented, everyone knows where to look. Then a developer needs to do something slightly unusual. They can't find the answer in the portal. They search the portal anyway because that's where they're supposed to look. They ask in Slack. Three hours later they have their answer, which wasn't in the portal because it was edge casey.
What actually works: keep the portal for onboarding and standard stuff. Everything else lives in the repo where people are already looking. A well-commented Makefile and a clear local setup script beats a portal page. Real example from my last gig - we ditched the Kafka documentation portal and just embedded everything in the library's README with actual consumer examples. Ship times on Kafka integrations dropped measurably.
This doesn't mean no portal. It means ruthlessly scoped. Onboarding flows, account setup, runbook links. That's it. The hard operational decisions shouldn't live in a separate system.
Totally tracks with what I've seen. The portal becomes a forcing function that slows down edge cases, which is most of what we actually build.
Better approach: portal as a search index over distributed docs, not the source of truth. Keep answers wherever they naturally live - repos, runbooks, team wikis - and make the portal just surface them fast.
We ditched centralized docs for tagged markdown files in the actual codebases. Took two weeks to set up. Paid for itself in the first month.
Yeah, I've lived this. Built one at my last gig. The portal became this beautiful graveyard while everyone just Slacked each other or dug through old repos.
The thing that actually worked: stop optimizing for discoverability first. Just make it trivial to update. We switched to a single markdown file per service, auto-generated from actual config, living in the repo. Ugly as hell. But when someone fixed something, the docs fixed themselves. Adoption went up because it wasn't stale by Thursday.
Golden paths are fine. But don't make them the bottleneck for the 20% of legit edge cases.
Seen this exact thing. The portal becomes a single point of friction instead of solving for the actual workflow. Developers still dig through Slack history and old PRs because that's where the real answers live.
Best outcome I've seen: minimal portal that's basically a router. Links to actual sources of truth - the mono repo README, the service's own docs, the runbook. Curate ruthlessly, but don't duplicate. Devs learn fast where to actually look, and you're not maintaining two versions of everything.
Tom Lindgren
Senior dev. PostgreSQL and data engineering.
I've seen this exact thing happen with data infrastructure. Teams build this pristine lakehouse docs site, standardize on dbt, create "golden path" templates. Then someone needs to join a dataset that doesn't fit the pattern and they're stuck because the portal enforces one way of thinking.
What actually worked: stop optimizing for discoverability first. Start with making the exceptions easy. Build your docs around real problems people hit, not ideal workflows. And critically, make it trivial to do things outside the system when needed. You lose some consistency but you unblock people fast.