The quick version: Docs-as-code has two versions in circulation and they rarely get distinguished. The narrow one says: write in plain text, use Git, work like an engineer. The broader one says: bring structure, rigor, and shared ownership to documentation work, using whatever tools best serve that goal. The narrow version works well for developer documentation. It gets into trouble everywhere else. The real value of docs-as-code is in its principles: structured authoring, content reuse, automation, and genuine collaboration between writers and SMEs—not its toolchain. Documentation should run in parallel with development, treated as a product feature, not a trailing deliverable.
Docs-as-code has quietly become one of the more loaded terms in technical writing. Mention it in a community forum and you’ll get enthusiastic advocates on one side and eye-rolls on the other, and both reactions are reasonable, depending on which version of docs-as-code you’re talking about.
That’s the problem. There are at least two versions in circulation. One is a narrow, toolchain-specific interpretation: write in plain text, version in Git, publish through a CI/CD pipeline, work the way engineers work and use their tools. The other is a broader, principles-based philosophy: bring the same discipline, rigor, and structural thinking to documentation that good software development brings to code. These two versions are often treated as the same thing, and they aren’t.
What started as a useful methodology becomes a mandate that optimizes for the wrong things.
The narrow interpretation has its place. For developer documentation (API references, SDKs, READMEs), it makes a lot of sense. But it has a tendency to travel beyond that context, getting applied to user guides, help centers, tutorials, and product documentation in ways that don’t serve the work or the people doing it. When that happens, what started as a useful methodology becomes a mandate that optimizes for the wrong things.
This article isn’t an argument against docs-as-code. It’s an argument for understanding what it actually is, and being deliberate about which version you’re adopting, for which documentation, and why.
What Docs-as-Code Actually Is
The term comes from a simple but compelling idea: documentation should be treated with the same care and discipline as software. The Write the Docs community, one of the more influential voices in technical writing, defines docs-as-code around five core practices: using issue trackers to manage documentation work, version control (typically Git) to track changes, plain text markup languages like Markdown or AsciiDoc for authoring, code reviews to maintain quality, and automated tests to catch errors before publishing.
The culture it was designed to create is worth noting: shared ownership between writers and developers, where both feel responsible for the quality of documentation and neither treats it as someone else’s problem. That’s a genuinely worthwhile goal, and it emerged from a real pain point. Documentation lagged behind releases, lived in silos, and was invisible to the engineering teams whose work it was supposed to describe.
Like many methodologies that solve a specific problem well, it began to travel. Somewhere in that journey, the toolchain and the philosophy got tangled together.
Docs-as-code, in this original context, was largely a response to the developer documentation problem. Open source projects needed contributors who could update docs the same way they updated code. Developer-facing products needed documentation that shipped with the product, not weeks after. Engineering-driven organizations needed a way to make documentation a shared responsibility rather than a bottleneck owned by one person or one team.
Those are legitimate problems, and docs-as-code addressed them. But like many methodologies that solve a specific problem well, it began to travel. Somewhere in that journey, the toolchain and the philosophy got tangled together in ways that are worth unpacking.
A More Expansive View of Doc-as-Code
Not everyone who works within a docs-as-code framework pictures Markdown files and pull requests.
Docs-as-code is often described in terms of tools. But at its core, it’s defined by a set of content properties that make documentation easier to maintain, reuse, and scale:
- Structured Content: Authoring content using open, semantic standards so it remains independent of any specific tool, vendor, or output format.
- Separation of Content and Presentation: Keeping content independent from its formatting and layout so the same source can be published across multiple formats and surfaces.
- Content Reuse: Designing content as modular components that can be reused intentionally across contexts, rather than duplicated and maintained separately.
- Versioning: Managing documentation changes through tracked, reviewable revisions so updates are deliberate, testable, and aligned with product evolution.
- Automation: Using tooling to handle repetitive processes such as publishing, formatting, validation, and deployment, so content can scale without increasing manual effort.
Notice what’s missing: no mention of plain text, no mention of Git, no mention of command line tools. Instead, the focus is on outcomes: consistency, portability, efficiency, reliability. The discipline of software development, applied to documentation, without prescribing the specific tools used to get there.
The tools don’t matter as much as the purpose and need. They should serve that purpose, not put the cart before the horse.
Why collaboration is the missing piece
One thing worth adding to this list: low-barrier collaboration between writers and subject matter experts, including product managers, engineers, and designers. Review and collaboration are where documentation quality is made or broken, and the barrier to participation has to be low enough that the people with the knowledge will actually show up. That means:
- review interfaces that minimize the effort required for SMEs to access and learn the tool,
- lightweight feedback mechanisms that fit into workflows they already use,
- and defined touchpoints that make collaboration a natural part of the process rather than an extra ask.
Shared ownership of documentation means nothing if the tools make collaboration impractical.
docs-as-code Doesn’t have to mean Markdown and Git
A technical writing team using Paligo is already doing docs-as-code:
- Paligo’s structured, standards-based authoring separates content from formatting and output type.
- Built-in versioning and branching mean doc updates follow a controlled review and release process, just like product features.
- Component reuse is built into the CCMS architecture rather than managed through copy and paste.
- Publishing pipelines automate delivery to hosted portals.
- And for SME collaboration, its dedicated Reviewer license strips away the full CCMS complexity to surface only the content and a comment sidebar, with SSO integration so reviewers aren’t managing yet another set of credentials.
The philosophy fits. The toolchain is simply the implementation that best serves the team’s workflow and documentation type.
The distinction matters because it shifts the conversation from how to why. The goal was never really to get writers into Git. It was to bring structure, rigor, and shared ownership to documentation work. The tools should serve that goal, and the right tools will look different depending on the team, the content, and the audience.
When the broader principles are the starting point, docs-as-code stops being a methodology that asks technical writers to work like engineers, and starts being a framework that any documentation team can apply on their own terms.
Where the Narrower Interpretation Works Well
The narrower interpretation of docs-as-code (plain text, Git, CI/CD pipelines) does have a natural home, and it’s worth being clear about where that is before critiquing where it isn’t.
Developer documentation is the obvious fit. API references, SDKs, READMEs, changelogs, code samples: these are documents that engineers often write themselves, live closest to the codebase, and need to stay in sync with releases. When the people writing the documentation are the same people writing the code, it makes sense for the toolchain to be the same too. The friction of context-switching between environments disappears, and documentation becomes a natural byproduct of the development process rather than a separate workstream.
The problem isn’t the approach itself; it’s the assumption that because it works here, it should work everywhere.
There’s also a practical argument for the “block the merge” mechanic that docs-as-code enables, which prevents a feature from being merged into the codebase until documentation is included. For developer-facing products especially, this is a genuine forcing function. It ties documentation accountability directly to the release process, making it structurally impossible to ship undocumented features. The documentation doesn’t get added later, when the engineer has moved on to something else and the details are no longer fresh.
In open source projects, the shared toolchain also lowers the barrier for external contributors to improve documentation alongside code, though it’s worth noting that external contributors who materialize reliably are rarer in practice than the theory suggests.
Where the narrower interpretation works, it works well. The problem isn’t the approach itself; it’s the assumption that because it works here, it should work everywhere.
Where the Narrower Interpretation Gets Overapplied
The leap from “this works well for developer docs” to “this should be how all documentation works” is where things start to break down.
User guides, help centers, tutorials, onboarding content, UX copy, in-app guides: these are not developer documentation. They serve different audiences, require different structures, and demand a different kind of craft. A getting started guide for a non-technical user isn’t just a README with friendlier language. It’s an information design problem: how do you sequence an experience so that someone with no prior context builds understanding progressively, without getting lost or overwhelmed? That kind of work requires a clear view of hierarchy, structure, and flow, none of which plain text authoring makes easier.
There’s also a persistent misconception about what technical writing actually is. Documentation work gets reduced to “writing” in a way that no one would reduce software development to “typing.”
In practice, technical writers are making decisions about information architecture, managing content reuse across multiple outputs, handling conditional publishing for different audiences or product tiers, maintaining taxonomy, coordinating localization, and managing review cycles with stakeholders who have competing priorities. Asking that work to happen in a plain text editor and a command line is like asking an engineer to write production code in Notepad: technically possible, but a poor match between tool and task.
When the narrower interpretation of docs-as-code gets applied to this kind of documentation, it optimizes for the wrong things. It makes the toolchain easier for engineers to interact with at the expense of making the work harder for the people whose full-time job it is to do it well.
What happens when documentation is treated as a downstream activity?
In practice, documentation is too often treated as a downstream activity. A feature gets built, and then someone remembers that it needs to be documented. By that point, the engineer who built it has mentally moved on to the next release, and often literally moved on to the next sprint. Getting them on a call becomes harder. Responses to Slack messages get slower. When you do connect, they’re recalling details from memory rather than from fresh context, and if they kept notes at all, finding them is its own project.
The technical writer is left doing archaeology on a feature that the person who built it would rather not have to revisit. The documentation that results isn’t necessarily inaccurate, but it’s harder to get right, takes longer than it should, and deadlines get missed while waiting for information to surface. And if we’re being honest, sometimes documentation gets published incomplete; not because the writer didn’t know better, but because the window closed and the information never fully materialized.
DDLC and SDLC Working in Tandem
If the broader, principles-based view of docs-as-code is the right framework, then the logical conclusion is this: the documentation development lifecycle (DDLC) and the software development lifecycle (SDLC) should run in parallel, with defined points of intersection, not as separate processes that occasionally collide at release time, like two people who only run into each other in the break room and call it collaboration.
Running the DDLC in tandem with the SDLC looks like this:
- Documentation tasks are created alongside feature tickets at the start of a sprint, not added as an afterthought at the end.
- Writers have visibility into what’s shipping early enough to make real decisions about structure, audience, and content strategy.
- Technical accuracy reviews happen before publication, with engineers as collaborators rather than last-minute fact-checkers.
- And documentation completion is a condition of ticket closure, not a separate workstream that finishes whenever it finishes.
Does syncing the DDLC and SDLC require a shared toolchain?
That last point is worth emphasizing because it doesn’t require everyone to share an authoring toolchain to implement. Tying documentation sign-off to ticket closure is a process decision, but one that becomes significantly easier when writers, engineers, and product managers are already working in the same project tracking tool.
If everyone is in Jira, for example, documentation tasks live where the work already lives, progress is visible to everyone, and the sign-off condition is built into a workflow the whole team already uses. The forcing function is the process, enabled by shared visibility; not a shared text editor or version control system.
The choice of how the DDLC and SDLC integrate should be holistic, driven by the documentation team’s size, the documentation type, the toolchain already in use, and the nature of the product being built. There is no single implementation that fits every context. What matters is that the integration is intentional, that documentation is treated as a parallel track rather than a trailing one, and that the process is designed around the needs of both the writers doing the work and the subject matter experts they depend on.
What Gets Lost When Toolchain Becomes Dogma
When a specific implementation of docs-as-code (plain text, Git, CI/CD) gets treated as the definition rather than one possible expression of it, the conversation shifts from outcomes to tools. And that shift has real consequences.
How does toolchain dogma affect technical writers?
The most immediate is that technical writers get asked to adopt an engineering workflow wholesale, rather than having a process designed around the needs of both teams. The assumption, often unstated, is that the writer should adapt to the engineer’s environment. Not because it makes the documentation better, but because it makes the writer easier to integrate into an engineering pipeline.
This reinforces a dynamic that many technical writers know well. That documentation, and the writer’s role itself, is somehow subordinate to engineering within the product team. Despite the fact that writers are full members of that team, contributing a distinct and necessary discipline.
When Git fluency becomes a proxy for competence
There’s also a quieter cost. When toolchain becomes dogma, it narrows who gets to be considered a “modern” technical writer. Familiarity with Git and command line tools becomes a proxy for competence, even for roles where those skills are largely irrelevant to the actual work.
Writers who have deep expertise in information architecture, structured authoring, content strategy, and audience design get filtered out in favor of writers who are more comfortable in a developer environment. The craft gets subordinated to the toolchain.
What happens to the underlying goals when tools become the focus?
Perhaps most importantly, when the toolchain is treated as the point, the broader principles get lost. The goal was never plain text for its own sake; it was structured, portable, reusable content. The goal was never Git for its own sake; it was version control, review discipline, and release alignment.
When those underlying goals get obscured by tool preference, teams can end up following the letter of docs-as-code while missing its spirit entirely, or rejecting the whole philosophy because the narrow interpretation didn’t fit their context.
The toolchain should serve the work. When it stops doing that, it’s worth asking whether the methodology has been applied, or merely imposed.
The Philosophy Was Always Bigger Than the Toolchain
Docs-as-code isn’t a bad idea. It’s a good idea that has been both undersold in its broader form and oversold in its narrower one.
The narrower interpretation (plain text, Git, CI/CD, work like an engineer and use their tools) solved real problems for a specific context and deserves credit for that. Developer documentation is better in many organizations because of it. The “block the merge” mechanic has made documentation a genuine part of the release process in ways that goodwill and process documents alone never managed to achieve.
But methodology travels faster than nuance. And somewhere along the way, a set of tools and practices designed for a specific kind of documentation and a specific kind of contributor became a generalized best practice. It was applied to contexts it wasn’t designed for, by teams it doesn’t serve well, in organizations where no one stopped to ask whether it was the right fit.
Where the real value of docs-as-code Live
The more expansive, principles-based view is where the real value lives. Structured content. Standards-based authoring. Deliberate reuse. Separation of content from presentation. Automation of mechanical tasks. Low-barrier collaboration between writers and the subject matter experts they depend on. These are outcomes worth pursuing regardless of what tool you use to pursue them, and they are achievable in Paligo, in Oxygen, in a CCMS, or yes, in Markdown and Git, depending on what your team actually needs.
The goal was never to make technical writers work like engineers. It was to bring the same rigor, discipline, and shared ownership to documentation that good software development brings to code. Those are not the same thing, and keeping them distinct is what allows both writers and engineers to do their best work, together, without either having to become the other.
Documentation is a product feature. The writers who create it are product team members. The processes and tools that support that work should reflect both of those facts; not as an afterthought, but by design.
Leave a Reply