Documentation has traditionally lived in tools designed specifically for writers: word processors, desktop publishing systems, wikis, and specialized authoring tools. Software development took a different path. Code moved into version control. Developers began working with branches, pull requests, automated tests, continuous integration, and automated deployments.

Over time, a similar idea emerged for technical documentation: What if documentation used the same tools and workflows as software development? This approach became known as Docs as Code or Docs Like Code.

Today, Docs as Code is widely used for developer documentation, API documentation, open-source projects, and technical documentation in software companies. But while this philosophy works extremely well for technical teams, it can be challenging for mixed teams with non-technical users. Later, we will look at these challenges, often described as the People Problem, and discuss a unified or hybrid solution that might work well for both sides.

What does Docs as Code mean?

The Write the Docs community describes Docs as Code as a philosophy of writing documentation with the same tools used for code, including version control, plain-text markup, code reviews, issue trackers, and automated tests.

The important word is philosophy. Docs as Code is not a particular software product. You can implement it with many different combinations of tools. The common idea is that documentation becomes part of the technical workflow rather than being written in a proprietary authoring application and published from that application.

Why did Docs as Code emerge?

There is no single moment at which Docs as Code was invented. Many of its individual practices are much older than the term itself. Developers and technical writers were using plain text, version control, automated builds, and generated documentation long before anyone consistently called the approach "Docs as Code." The term became useful because several developments came together.

First of all, open-source software changed documentation. Projects such as Python, OpenStack, Django, and many others needed documentation contributions from developers and community members distributed around the world. The same infrastructure that made distributed software development possible also provided a natural foundation for collaborative documentation. The result was a documentation workflow that looked increasingly similar to software development.

The history of Docs as Code is closely connected to the broader documentation community that formed around Write the Docs. Write the Docs was founded in 2013 by Troy Howard, Eric Redmond, and Eric Holscher. Eric Holscher was already known for Read the Docs, a documentation hosting platform that had become important in the Python community. The founders initially wanted to create a place where people interested in documentation could meet and exchange ideas. Their first announcement on Hacker News attracted hundreds of people, eventually leading to a conference and a growing international community.

One of the most influential people in the Docs as Code movement is Anne Gentle. Gentle worked extensively on documentation in open-source and enterprise environments and later led developer experience and documentation initiatives at Cisco. Her book Docs Like Code helped turn the ideas behind the approach into a practical methodology. Gentle's definition is deliberately broader than simply "put your Markdown in Git." It includes collaboration, repeatable builds, automation, technical accuracy, consistency, and the involvement of developers and other contributors.

The main ideas behind Docs as Code

Although implementations vary, most Docs as Code systems share several principles.

  • Documentation is versioned: A document is not simply overwritten. Every change can be associated with an author, a commit, a branch, or a pull request. This makes it possible to track all changes and restore previous versions.
  • Documentation is reviewed: Instead of sending a document around as an attachment or asking someone to review a page in a CMS, contributors can review a change through a pull request.
  • Documentation can be automated: Once documentation exists as structured source files, many processes can be automated. A broken link, invalid Markdown, missing reference, or other problem can potentially prevent publication. This brings documentation closer to the concept of a build artifact.
  • Documentation can live close to the code: A common Docs as Code pattern is to keep documentation in the same repository as the software it describes. When the software changes, the documentation change can happen alongside it. This is particularly powerful for API and developer documentation.

A typical Docs as Code setup

A typical Docs as Code workflow combines different tools. The documentation is usually stored as plain-text source files in a version-control system like Git along with the code. A typical repository looks like this:

software/
├── src/
├── tests/
└── docs/
    ├── getting-started.md
    ├── configuration.md
    └── api.md

The source is normally written in a lightweight markup language. Common choices include Markdown, reStructuredText, and AsciiDoc. Markdown became particularly influential because it is easy to read without rendering and is supported by an enormous ecosystem of tools. AsciiDoc is popular in environments where more sophisticated document structures and publishing requirements are needed.

A change can be reviewed as a diff, associated with an issue, merged together with a software change, tested automatically, and eventually published through the same or a similar CI/CD infrastructure used for the product itself. A simplified workflow can look like this:

Author
   │
   ▼
Markdown / AsciiDoc
   │
   ▼
Git repository
   │
   ▼
Pull request
   │
   ▼
Review + checks
   │
   ▼
Merge
   │
   ▼
Automated build
   │
   ▼
Published documentation

A mature Docs as Code workflow can contain many additional tools, such as Markdown or AsciiDoc linters, link checkers, spell checkers, inclusive-language checks, diagram generators, API specification tools, automated tests, CI/CD systems. The resulting toolchain can become surprisingly sophisticated.

The advantages of Docs as Code

The approach has several obvious strengths.

  • Better collaboration with developers: Developers already understand Git, branches, pull requests, and code review. Using the same workflow for documentation reduces the conceptual distance between software and its documentation.
  • Documentation can follow software changes: When documentation and code are changed together, documentation does not have to wait for a separate editorial process. This can be especially useful for APIs and developer-facing products.
  • A complete history of changes: Git provides a detailed history of documentation changes. This is useful for auditing, troubleshooting, and reverting mistakes.
  • Automation: Builds, tests, link checking, previews, and deployments can all become automated.
  • Lower tooling barriers: Plain-text files and open-source tools can make it possible to build a documentation system without committing to an expensive proprietary authoring environment.
  • Developers can contribute: Perhaps the most important cultural advantage is that documentation becomes easier for developers to contribute to. Instead of asking a developer to open a separate documentation system, a documentation change can be made alongside the code.

But Docs as Code has a people problem

This is where the discussion becomes more interesting. The technical advantages of Docs as Code are relatively easy to explain. The human advantages are more complicated.

A developer may find this workflow natural:

clone → edit → git commit → push → pull request → review

A technical writer who already works with Git may be perfectly comfortable with it too.

But what about:

  • a product manager?
  • a customer-support specialist?
  • a subject-matter expert?
  • a marketing employee?
  • a consultant?
  • a client?
  • someone who only needs to correct two sentences?

For these contributors, a Git-based workflow can introduce substantial friction. One technical writer on Reddit recently described Docs as Code as the most technically intensive authoring environment they had encountered, with much of their time spent learning and navigating VS Code and GitHub rather than concentrating on writing.

There is an important counterargument. Anne Gentle has specifically pointed out that the GitHub browser has changed the accessibility of Docs as Code: contributors can edit files directly in a browser without setting up a complete development environment. That makes Docs as Code considerably more approachable.

But there is still a distinction between: "You can edit this file in GitHub." and "This is a comfortable documentation environment for your entire team." The first is a technical capability. The second is an editorial experience.

And there are more potential trade-offs when it comes to practical implementation:

  • Distributed Documentation: Docs as Code often places documentation alongside the code it describes. This works well when one product maps neatly to one repository. But documentation often crosses product and repository boundaries. A user manual, for example, may cover a platform, several applications, an API, and related services. Keeping these parts in separate repositories can make it difficult to maintain a single source of truth, consistent terminology, navigation, and publishing workflow.
  • Toolchain Complexity: A mature Docs as Code workflow can involve Git, a repository platform, a markup language, a documentation generator, a theme, plugins, linters, link checkers, diagram tools, CI/CD pipelines, hosting, and other services. Each component solves a specific problem, but together they create a chain of dependencies that needs to be configured, updated, and maintained. Over time, the documentation system itself can become a technical project.
  • Static Publishing: Many Docs as Code workflows ultimately publish documentation as a static website. Static sites are fast, secure, and easy to deploy, but they also provide a relatively limited application layer. Editing, authentication, user roles, permissions, personalized content, workflows, and other dynamic features are not normally part of the publishing model. These capabilities can be added through external services, but doing so introduces another layer of infrastructure.
  • Governance and Permissions: When documentation is stored alongside software, its access and review process can become tied to the permissions and governance of the software repository. This works well when the same people maintain both code and documentation, but becomes more complicated when documentation has a broader audience of contributors.
  • Not All Documentation Is Code-Adjacent: Docs as Code is particularly powerful when documentation changes together with software. But not all documentation has such a close relationship to code. User manuals, conceptual guides, onboarding content, policies, and organizational knowledge may span several products or evolve independently of software releases. For this type of content, forcing everything into a software repository can add structure without necessarily adding value.

From Docs as Code to Docs for Teams

This leads to a possible evolution of the original idea. Docs as Code solved an important problem: How can documentation become part of the software development workflow? The next question is: How can the same documentation workflow remain accessible to the entire team?

That does not require abandoning Git. In fact, Git can remain the source of truth while different people interact with the documentation through different interfaces.

For example:

flowchart TB
    D[Developers] --> GP[Push / Pull]
    E[Editors] --> BC[Browser / CMS]

    GP --> G[Git]
    BC --> G

    G --> DOC[Documentation]
    DOC --> W[Website]

The idea is not to replace Docs as Code. It is to make the Docs as Code source accessible through more than one workflow.

This is particularly relevant in two situations:

  • When developers maintain the technical foundation but product managers, support teams, technical writers, or subject-matter experts also need to edit the content.
  • When documentation does not fit naturally into a single software repository because it belongs to several products.

Docs as Code is not necessarily a static website

One common misconception is that Docs as Code means "write Markdown and generate a static website." That is one implementation, but it is not the definition. The essential idea is the workflow:

source → version control → review → automation → publication

The final publishing system can be a static website, a documentation portal, a PDF, an internal system, or another output. This distinction is useful because it separates the practice from the toolchain.

Where Flat-File-CMS fits

A flat-file CMS takes a somewhat different approach from a typical static documentation generator. Most flat-file CMSs also use plain Markdown files, like static site generators. But unlike static site generators, a flat-file CMS generates the website dynamically. This means that a flat-file CMS can provide the same authoring experience as a traditional database-driven CMS. Documentation can remain file-based and Markdown-based while authors work through a browser-based content management interface.

Typemill is one of these flat-file CMSs, and it is especially useful for documentation projects. With the GitSync plugin, Typemill can synchronize Markdown content with one or more GitHub or GitLab repositories. It can also generate websites and PDFs from the Markdown content, allowing for a more sophisticated hybrid workflow:

flowchart TD
    D1[Developer 1] --> MD1[Markdown] --> G1[Git 1] --> GS[GitSync]
    D2[Developer 2] --> MD2[Markdown] --> G2[Git 2] --> GS

    E[Editor] --> T[Typemill CMS]
    T --> MD[Markdown]
    MD --> GS

    T --> W[Website]
    T --> PDF[PDF]

The interesting part is not simply that Git is supported. It is that Git and a browser-based CMS can represent two different interfaces to the same documentation workflow.

Developers can stay in their familiar Git workflow, while non-technical users regain the role of editor and publisher that can be lost in a pure Docs as Code setup. They can decide what is ready to publish, which content is intended for which audience, and which outputs, such as websites or PDFs, need to be generated.

This makes the CMS more than just a friendlier Markdown editor. It becomes the editorial layer between the documentation source and its different audiences and outputs, while Git can remain the development and collaboration layer underneath.

AI changes the documentation workflow again

Docs as Code emerged in a world where documentation depended on manual workflows and dedicated tools like linters. AI is changing this equation. AI can write, rewrite, translate, summarize, structure, review, and check documentation. It can work with source code and documentation at the same time. Tasks that previously required specialized tools or a carefully assembled documentation pipeline can increasingly be handled by an AI assistant.

This can make the traditional distinction between technical and editorial toolchains less important. The developer can use AI inside the development workflow, while the editor can use AI inside the CMS. Both can work with the same Markdown content without having to use the same tools.

The result is a simpler model with less tooling:

flowchart TD
    D[Developers] --> GA[Git + AI] --> M[Markdown]
    E[Editors] --> CA[CMS + AI] --> M
    M --> S[Shared documentation]
    S --> AC[AI Chatbot]

The collaboration of technical and non-technical editors brings Markdown back to one of its original strengths. Markdown was designed as a common language between technical and editorial workflows. Developers can work with Markdown in Git repositories, editors can work with the same Markdown through a CMS, and AI agents can read and modify it in both environments.

Even reusable AI instructions, agent definitions, skills, and other AI-related resources can be represented as Markdown files. They can therefore be versioned, shared, reviewed, and edited alongside the documentation itself.

And you can go a step further. Typemill, for example, can also integrate AI into the presentation layer and provide a simple "Ask the Docs" chatbot for readers, without requiring a complicated RAG setup.

Is Docs as Code the future of documentation?

For some kinds of documentation, it already is. But the future of Docs as Code does not have to mean that everyone works like a developer.

The real opportunity is to keep the strengths of the software development workflow while making documentation accessible to everyone who contributes to it. Technical writers can work with Git and pull requests when that suits them. Non-technical writers can work through a CMS with a familiar editing experience. AI can assist both sides with writing, editing, translation, review, and other tasks.

The underlying documentation does not have to change just because the workflow does.

A possible model looks like this:

  • Git for versioning and collaboration.
  • A CMS for accessible editing and content management.
  • AI for writing, editing, review, and assistance.
  • Markdown as the common language between different workflows.
  • Automation for publishing and quality assurance.
  • One documentation system that brings these workflows together.

The interesting future may therefore not be Docs as Code versus CMS, but Docs as Code for everyone.

That is the idea behind moving from Docs as Code to Docs for Teams.