Documentation as Code
This article was written in 2022, and my tooling preferences have changed since then. Following the release of Nextra 3, remote MDX files are now supported, and I have since migrated to using it. However, the idea of Documentation as Code is still relevant.
I spent last week working on “Contented”. Contented is a Markdown-based authoring workflow that encourages a developer authoring within its contextual Git repository.
If you don’t make it easy to get something done (authoring), nobody will go out of their way to get it done perfectly every time. Turn it into a GitOps workflow and give people the necessary tools and power to get it done perfectly every single time — everyone will get it done, as now there is no other way else to get it done. An efficient workflow naturally satisfies.
The Ballad of Engineering typically goes like this
- While at SaaS Team
- Engineer writes code
- Engineer writes tests
- Engineer publish/merge/release code & tests
- Separately while at Product/Marketing Team
- Engineer writes documentation
- Engineer publishes documentation into a separate site
Contented Workflow
Contented is a prose bundler for your documentation with pipeline driven authoring-oriented workflow to encourage developers authoring within its contextual Git repository.
- While at SaaS Team
- Engineer writes code
- Engineer writes tests
- Engineer writes docs
- Engineer publish/merge/release code, tests & docs
- Separately while at Product/Marketing Team
- CI pulls versioned docs automatically from SaaS team and publishes it.
Contented Design
With a headless design of 1 config file contented.config.mjs, developers can start writing
their markdown content and preview it on their localhost contented generate --watch.
Choosing convention over configuration reduces HTML/UI clutter, allowing developers to focus on authoring.
Authored content can be continuously delivered (CD) into a hosted static site (e.g., GitHub Pages/Netlify/Vercel) for
preview contented generate. As code drift, so does documentation; this allows each pull request to have an
accompanying sharable preview of the documentation. With CD, it effectively shift-left your documentation workflow and
checks it is compilable and presentable.
By encouraging authoring next to the source (in the same git repo), developers can contextually document changes as they
develop. All domain-specific changes will go into the main branch with one Git Pull Request.
With contented build, you can compile your prose into sources index.js and *.json. That output
into ./dist to npm publish them into any registry of your choice, for you can
easily npm i @your-scope/your-npm-package and use the processed content on any of your downstream sites. Easily
pulling up-to-date content and prose from individual domain-specific repositories and re-presented. Think microservices,
but for your prose!