What it takes to build docs worth reading

Treating docs as a product

When documentation lives as an afterthought, it shows. Pages drift out of date, examples break quietly, and release notes scatter across a dozen places no one can find. The fix is not a weekend cleanup. It is a decision to treat docs the way you treat any product people depend on: someone owns it, it has standards, and it gets maintained on purpose.

That is the decision I made when the docs came to the Developer Relations team at the end of 2025. Not "let's tidy this up," but "this is ours now, and we are accountable for whether a developer can actually build from it."

The work, in the repository

The honest record of what a team does to a codebase lives in its git history, so that is where the story starts. Comparing the six months before the handoff to the six months since:

Before vs. Under DevRel:

Commits: 476 → 1,900+
Merged pull requests: 145 → 447
Unique contributors: 21 → 64

A repository that averaged fewer than 500 commits over half a year is now past 1,900 in the same span. The contributor count tripled, because we treated the docs as something the whole community could improve, not a walled garden. This is what a team that decided to do the work looks like when you measure it.

Our proudest metric is what was cut

In six months, we added roughly 339,000 lines and removed roughly 281,000.

That near balance is the point. A neglected docs site accumulates: dead pages, stale tutorials, examples that no longer compile, three slightly different explanations of the same concept. Adding more on top of that does not help anyone. So we cut nearly as much as we wrote.

We rebuilt the Hello World walkthrough from 1,300 lines down to about 300 without losing a thing. We consolidated scattered release notes into a single clean reference. A docs site is judged by what a developer can find and trust, not by how much sits on the shelf.

A library you can learn from

At the start of the year, the examples library had effectively one usable entry. Today, there is a progression a developer can climb, and every example demonstrates something specific about building on Midnight:

Alongside these sit a set of example contracts (a calculator, an election, a private guest list, a private reserve auction, token transfers) that did not exist before this year. Each one is built to be read, copied, and learned from. We retired the examples that taught nothing specific to Midnight, because an example that could belong to any chain is not teaching anyone why they are here.

Built to stay current

The hardest part of documentation is not writing it. It is keeping it true as the thing it describes keeps changing. A network moving as fast as Midnight breaks docs constantly if no one is watching.

So we built the watching into the process. There is now an automated review pipeline that checks every documentation change for quality and accuracy before a human ever looks at it. When a recent release changed import patterns across the codebase, the system flagged downstream content that would have become stale, and we held the update until it was corrected. That is the difference between docs you publish and docs you maintain.

AI tooling built for Compact

There is one more piece worth calling out, because it solves a problem unique to building here. Compact was not in the training data of the frontier AI models that developers reach for first. That meant the AI assistance developers now expect from every other ecosystem simply was not there for Midnight, and worse, a model would confidently invent Compact that does not work.

So we built the missing piece. Midnight Expert is a purpose-built knowledge base that teaches AI coding assistants to treat their Compact guesses as unreliable and verify against the real compiler and runtime tools before presenting anything to a developer. The same platform powers the automated documentation review described above, checking changes for accuracy before a human reviewer sees them.

If you are building on Midnight with an AI assistant in the loop, start there at midnightntwrk.expert.

The team behind it

This was a team effort in the truest sense. Jay Albert, our DevRel Engineer, Nick Stanford, our DevEx PM, and Idris Olubisi, our Developer Educator, built and rewrote example after example. Emmanuel Ameh, the newest member of our team and our Technical Writer, joined this year and took on the standards work end-to-end.

Nick also owns the release process that keeps every page in sync as the network changes—the continuous work that prevents documentation from going stale. And we brought in HackMamba to add concentrated firepower to align with the network launch deadline, with a substantial hand in the rebuild. None of the numbers above would have happened without these people.

Come build

I am not going to tell you the work is finished, because good documentation is never finished. It tracks a living network, and the network is still growing fast. What I will tell you is that the foundation is real now, the examples work, the tutorials are current, and a deeply engaged team is behind them every day.

If you have built on Midnight before, the docs are not the ones you remember. If you are new, you are arriving at a better starting line than the developers who came before you. Either way, the door is open.

Come build at docs.midnight.network, and tell us where we can do better.

推荐订阅源

DEV Community