Docs as code

Docs as code solved one problem and created another

Putting the documentation in the repository stopped it drifting away from what shipped. It also made the documentation reachable only by people who can operate a repository, which is most of your engineers and almost none of the other people who write.

What it is

Docs as code means keeping the documentation in the same repository as the software, in plain text, reviewed and versioned the way the code is. A change to a runbook arrives as a diff. A spec has an author, a date and a history. The files are usually Markdown, they sit in docs/ or beside the module they describe, and they ship on the same branch as the thing they document.

That is the whole practice. There is no product to buy and no standard to conform to. Teams arrive at it from different directions and end up in roughly the same place: the documentation lives where the work lives. The canonical description is Write the Docs' guide, which is where most of the arguments about it still start.

Why it won

For years documentation lived somewhere else. A wiki, a shared drive, a hosted workspace. The problem was never that those tools were bad at writing. It was that the document and the thing it described drifted apart, quietly, and nobody found out until somebody followed a runbook that had been wrong for eight months.

Putting the documentation in the repository fixes that by construction. The change to the code and the change to the document are the same change, reviewed by the same person, at the same time. If the document is wrong, it is wrong in a diff somebody has to approve.

Then the agents arrived and settled the argument. Coding assistants read and write Markdown natively, and they are strongest on files that are in the repository they are already working in. A specification the agent can read is worth more than a beautiful one it cannot. Over the last two years that turned docs as code from a preference into the obvious choice, and the volume of documentation arriving as generated Markdown went up sharply at the same time.

The cost nobody writes down

Every article about docs as code is about the first half. Here is the second.

The moment the documentation moves into the repository, it becomes reachable only by people who can operate a repository. Not "technical people" in the abstract - specifically, people who are fluent in clone, branch, commit, push, pull request, and what to do when a rebase goes sideways.

That is most of your engineers. It is almost none of the other people who write documentation.

The product manager who owned the spec stops editing it and starts sending paragraphs to an engineer to paste in. The designer who used to leave three comments on a flow now leaves them in a chat message that nobody links to the document. The support lead who knows the runbook is wrong files a ticket about it instead of fixing it. The technical writer, who is the person actually best at this, ends up with the worst tooling they have had in a decade.

None of this shows up as a problem. It shows up as documentation that slowly stops being written by anyone except engineers, and as review that quietly becomes optional because the people who would have reviewed it cannot open it.

To be fair about it: if your team is entirely engineers, none of this applies and docs as code has no downside worth discussing. This page is about the other case, which is most teams.

The workarounds, and what each one costs

Each of these is a reasonable choice and each of them is paying for the same missing thing: an ordinary way to read, edit and review a Markdown file in a repository, for somebody who does not want to learn git to do it.

Questions people ask about docs as code

Do you need to know git to do docs as code?

In the ordinary setup, yes - clone, branch, commit, push, and a pull request to get a change reviewed. That is the part nobody writes down when they recommend the practice, and it is why documentation in a repository tends to end up written only by engineers. The skill you actually need is not writing; it is git.

What tools does docs as code need?

A git repository, the documents as plain text - almost always Markdown - review through the same pull requests the code uses, and usually a static site generator to publish them. That is the whole stack, and none of it is a purchase. The gap is in the editing: the tools assume whoever writes is comfortable in a repository.

Is docs as code better than a wiki?

It is better at drift, by construction: the change to the code and the change to the document are one change, reviewed together. A wiki is better at participation - anybody can open it and type. Which one is right depends on whether your documentation is going stale or going unwritten, and most teams have only one of those problems.

Who writes the documentation in a docs-as-code team?

In practice, engineers, because they are the people who can reach it. The product manager, the designer, the support lead and the technical writer either send their edits to somebody else to paste in, or stop. That is not a fault in anyone's discipline; it is what happens when the documentation lives behind a tool only part of the team can operate.

Where Notula fits

That is the gap Notula is built for. It is a WYSIWYG Markdown editor that opens a git repository as a tree of documents: no syntax on screen, comment threads on any passage committed beside the document, and publishing is one sentence about what changed rather than a commit, a push and a pull request. Nobody is shown a rebase, a stash or a conflict marker. The files stay ordinary .md in your own repository, so everything above about drift and review and agents is still true.

It does not replace docs as code, and it does not want to. It removes the entry fee.

Download for macOS Download for Windows See what it does

Free, and it stays free. No account, no server. macOS and Windows.