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:

• 
  
  


• 
  
  


• (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. .

  
  
  

  
  
  
  The team behind it
  

  
  
  

  This was a team effort in the truest sense. , our DevEx PM, and , 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 , and tell us where we can do better.

  Vollständiger Original-Bericht

  Ausführliche Details, Code-Beispiele & Hersteller-Stellungnahme auf dev.to.

  ↗ Original-Artikel auf dev.to lesen