Git is Too Complex
Git is just a file system. Writers don't need to understand branching, merging, or rebasing. They just need to edit files and commit them. The complexity is hidden behind a simple UI like GitHub or GitLab.
Opinion • 2025
Why Docs-as-Code Is the Only Sane Way to Manage Documentation in 2025
Compose. Compile. Ship.
BY SARAH JENKINS
JANUARY 15, 2025 • 8 MIN READ
The Silent Killer of Technical Teams: Documentation Rot
It happens every year. You start a new project, excited to build something great. You write the code, you run the tests, and you ship the feature. But somewhere in the back of your mind, there's a nagging feeling: Did we document this?
Fast forward six months. You're debugging a legacy system. You open the "official" wiki. The last edit was made in 2019. The API endpoint you're looking for has been deprecated for two years, but the documentation still says it's active. The screenshots are pixelated. The links are dead.
This is documentation rot, and it is the silent killer of technical teams. It happens not because writers are lazy, but because the current model of documentation management is fundamentally broken.
Traditional documentation lives in a silo. It's often stored in proprietary tools like Confluence or SharePoint, locked behind permissions, disconnected from the codebase, and updated manually by a small subset of the team. When a developer changes an API, they update the code. They rarely update the docs. Why would they? There's no automated feedback loop. There's no version control. There's no peer review.
The Shift
What Docs-as-Code Actually Means
Docs-as-Code (DaC) isn't just about writing Markdown instead of Word. It's a paradigm shift that treats documentation as a first-class software artifact.
It's Version Control
When your documentation is stored in a Git repository alongside your code, it gains the same safety net. You can see who changed what, when, and why. You can roll back a bad edit. You can review changes before they go live.
It's Peer Review
Just like code, documentation should be reviewed. A senior engineer can review a PR to ensure technical accuracy. A product manager can review it for clarity. This creates a culture of shared ownership and continuous improvement.
It's Automated Publishing
With DaC, you can build a pipeline that compiles your docs into HTML, PDFs, or API specs automatically every time you push to the main branch. No more "I'll update the PDF later." The PDF is always up to date.
It's Testable
Yes, you can test your documentation. You can write scripts that validate that every API endpoint mentioned in the docs actually exists and returns the correct schema. You can validate that all internal links are valid. This catches errors before they reach the end user.
It's Accessible
Because your docs are just text files, you can use the same tools and techniques to make them accessible to everyone on your team. Screen readers, syntax highlighting, and search indexing work out of the box.
Common Objections
Addressing the "Writers Can't Use Git" Myth
It Breaks the Workflow
On the contrary, it streamlines the workflow. Writers can work in their favorite editor (VS Code, Sublime, Notepad++) and see their changes reflected instantly. They don't have to wait for a "publish" button to be clicked by a central admin.
It's Too Technical
Modern documentation tools abstract away the Git complexity. You can use a visual editor that syncs to Git, or simply rely on the fact that Git is now a standard skill for anyone working in tech.
The Solution
Building the Right Toolchain
Adopting DaC is easy. Adopting the right toolchain is where it gets tricky. You need a system that handles the heavy lifting so your writers can focus on writing.
Versioning
Git Integration
Store your Markdown, AsciiDoc, or reStructuredText files in a Git repository. Use pull requests to review changes. This ensures that every update is traceable and approved.
Templating
Pipeline Automation
Use a pipeline tool like Texkit to compile your source files into HTML, PDF, or API specs. Define your templates once and apply them to all your documents automatically.
Validation
Schema Enforcement
Define a JSON Schema for your documentation metadata. The pipeline will validate your content before publishing, catching errors like missing API keys or broken links.
Case Study
Migrating a 500-Page Wiki
Let's look at a real-world example. Acme Corp, a leading logistics company, had a legacy wiki with 500 pages of technical documentation. It was a mess of broken links, outdated screenshots, and inconsistent formatting.
Their team decided to migrate to a Git-backed documentation pipeline using Texkit. Here's how they did it:
- Phase 1: Extraction. They used a script to scrape the wiki and export the content to Markdown.
- Phase 2: Cleanup. They used a simple find-and-replace script to fix basic formatting issues and remove proprietary markup.
- Phase 3: Validation. They defined a JSON Schema for their API documentation and used Texkit's validation plugin to catch any missing fields.
- Phase 4: Publishing. They set up a GitHub Actions workflow that runs Texkit every time they push to the main branch, automatically publishing the docs to their internal portal.
The result? A 100% accurate, up-to-date documentation site that is now maintained by the entire engineering team. The migration took two weeks, and the ROI was immediate.
Ready to Ship Better Docs?
Documentation shouldn't be an afterthought. It should be a first-class citizen of your software development lifecycle.
Related Reading
More from the Blog
The State of Technical Writing in 2025
Exploring the trends that are shaping the future of technical communication, from AI-assisted writing to immersive documentation.
How to Write API Documentation That Developers Actually Read
A guide to creating clear, concise, and useful API documentation that reduces support tickets and improves developer onboarding.
The Economics of Documentation
Calculating the cost of documentation rot and the ROI of investing in a robust documentation toolchain.