DevDocs Platform
An internal documentation platform built as an MDX repo, so contributing docs feels like writing code rather than filling in a wiki.
An enormous amount of contextual information about a project lives nowhere except in one developer's head.
We're encouraged to share knowledge as often as we can, and that helps, but it doesn't really solve the problem. It takes real time to bring another developer up to speed on a project, and then you're relying on them to retain it even though they may never touch that codebase again.
The failure modes are predictable. The one developer who knows a project's infrastructure inside out goes on annual leave, and you can't put the project on hold until they're back. Or they leave the company, and unless there's been a rigorous handover — which there often hasn't — the knowledge goes with them.
What if we had a platform to centralise all developer knowledge and documentation?
The Problem
Four things compound, and they're all versions of the same issue:
- Knowledge is fragmented across individual team members.
- There's no centralised documentation to fall back on.
- Onboarding a developer onto an unfamiliar project is slow.
- Maintaining a project without its original developer is difficult.
There's no shortage of tools for this. Atlassian wikis, Confluence, GitHub Pages — all of them solve the centralisation part. But without a paid plan most are restricted, and the paid plans are expensive for a smaller team, which is how you end up with documentation that technically exists somewhere nobody has a licence for.
The harder problem is behavioural anyway. Any documentation platform is only as good as the contributions it attracts, and developers do not enjoy writing docs in a wiki editor.
What I Built
I wanted something that read like a team guide but felt like a repo to contribute to. The way to get developers writing documentation is to put it in a tool they already work in every day.
So the platform is an MDX repo. It's searchable like any documentation site, and you contribute to it exactly like a GitHub repo — branch, write MDX, open a PR.
I found an existing Next.js documentation project that already had MDX support and search, forked it, and built it out to suit us. The addition that mattered most was templating: example templates plus a script that generates a new route from one, so a developer only has to write content and never has to think about the platform's structure.
The template does a second job I hadn't planned for. By defining the sections up front, it answers "what counts as useful documentation?" Which is the question that stalls most people before they've written a word.
How It Works
What actually goes in it
The content is deliberately broader than "how this project works". Each project's docs cover:
- A timeline of events across the project.
- The approach taken to data migrations.
- Scopes and solutions for features and apps built for that client.
- A go-live checklist.
- The general context that normally only lives in a developer's head.
That last category is the whole point. "How stuff works" can often be recovered by reading the code. Why a decision was made, or what was tried first, cannot.
Letting an agent write the first draft
Once AI agents became genuinely useful, I added a workflow for connecting an agent to a project. It generates a prompt that directs the agent to scan the codebase and fill in the documentation process.
The advantage is that it fits the moment when documentation is least likely to get written: you run it as a job at the end of a project, when everyone's attention has already moved to the next thing.
From project docs to a team handbook
The platform drifted, usefully, beyond project documentation. We started adding workflows, demos, guidelines and best practices, and it became the place the team goes to align on how we work rather than just what we built.
That shift happened on its own, which suggests the format was right, people put things somewhere because it's the path of least resistance, not because they were told to.
What It Changed
- Onboarding onto an unfamiliar project takes less time.
- Documentation is centralised and searchable rather than scattered.
- Writing docs is a low-friction part of the development workflow instead of a separate chore.
- Projects are less dependent on the availability of one specific developer.