What docs as code really means

I’ve recently started a new job as a documentation engineer. While my work is largely the same as that of a technical writer, the sound and semantics of my new job title gave me some pause and made me think about what it really means to be doing docs-as-code. To say that it’s about writing documentation using the same tools and methods as software developers is correct, but fails to acknowledge the full consequences of the fact. Most descriptions of docs-as-code are naive because they stop at the implications of being developers’ attachés.

So what does docs-as-code really mean beyond the ability of building the docs from text files and versioning them using git? Is there anything beyond attending scrum ceremonies as friendly auxiliaries, smiling at the privilege of sitting at the same table as the almighty coding knights? I think so. I’ve built a career around the belief that technical writers are essential to all kinds of engineering efforts and deserve the same level of respect, resources, and recognition as their peers. Let me tell you why I think so.

Documentation is vital software infrastructure

Writing good documentation is key infrastructure work. Remove documentation, or fail to provide it, and your products cease to exist, their inner workings left to the imagination of users who have better things to do than divining the behavior of API endpoints or CLI options by looking at obscure code (if code is available at all). Docs are infrastructure because they allow people to use the product without being the product. In that, they share the same importance of servers, routers, and cloud service providers.

You don’t work on docs because they are good for SEO. You work on docs so that multiple areas of your business don’t crumble overnight. Without docs, sales engineers won’t have anything to show to the customers when their proof of concept tests fail. Take away docs and customer support won’t be able provide quick and repeatable solutions to users in distress. Ignore docs and users just won’t know about the new feature you just launched, your growth KPIs taking such a heavy hit that you wished you had something more than a newsletter.

If this sounds dramatic it’s because infrastructure failures are dramatic. When we say docs-as-code, what we’re really saying is that technical writers are performing critical work close to the code and to the reality of its development. Docs-as-code is not, in this sense, a symbolic gesture of writerly solidarity towards engineers: it’s becoming engineers to help products ship, succeed, and sustain themselves autonomously. And when we say docs, it’s not just manuals, but also embedded documentation, from UI texts to context help to error messages.

Docs-as-code require shared accountability and standards

If docs are infrastructure, it naturally follows that docs must be published following the same methodology your organization applies to code and key deliverables. If you don’t review, check, and merge docs the same way your org reviews, checks, and merges code, you’re not doing docs-as-code — you’re doing docs-as-bore. You have to treat docs with the same care as code. You would never push code into production without a proper review and tests: don’t publish docs in a hurry either–because docs are infrastructure.

Having documentation in the definition of done is not enough. There have to be standards and rules in place. Or, if your organization doesn’t follow any formal procedure for developing and merging features, docs can lead by example. Docs are the way your products communicate to users, their tongue: structured, comprehensive, accurate, and well tested documentation can often compensate for hasty product development much in the same way good infrastructure can cope with inefficient code, even if momentarily. Docs mitigate and alleviate.

Being a docs-as-code technical writer, or a documentation engineer, means that your success should be measured by the success of the feature itself, through docs observability and metrics that show the impact of documentation as part of the product, not as an external action. Measuring the success of documentation on its own, using media-related metrics, is like determining the success of buttons based on how quickly they react to clicks, or the success of images by how quickly they load. What matters is their purpose.

Docs and DocOps are a shared concern and responsibility

In modern software development teams, software developers are not only concerned with programming, but also with tending to test and build infrastructure, or what is commonly known as DevOps. This doesn’t mean that companies can’t have dedicated DevOps specialists or strategists–in fact, they do; rather, it shows that software engineering doesn’t stop at the drawing board or the text editor. It concerns itself with how the final product is assembled. Take that a step further and docs are part of the engineering bundle.

Documentation engineers, or technical writers, are the specialists and strategists, or the editors if you will, of a shared documentation effort that is integral to software development. Instead of taking away writing duties from software developers, the existence of technical writers increases the visibility and importance of docs, promotes best practices, and creates a sense of shared ownership of documentation. Writers who content themselves with tending to their closed garden of words are doomed to fail or fade away.

We’re slowly getting there. Books on technical writing for software developers have recently become popular; they are partially right in showing that the way for great documentation requires greater training and care from the side of engineers, but that misses the need for people who can coordinate the entire function, and those are technical writers. Both sides need each other: you can’t move the needle of great docs without the dedication of the entire engineering org, and engineers struggle to create great docs without a docs architect.

Going beyond docs-as-code as an authoring method

Representing docs-as-code as a mere authoring method does not render justice to the role of docs in software. We’re not using git and Markdown to ingratiate ourselves with developers, but to get closer to the product and reduce the communicational divide between us. As docs engineers, we’re not just scribes recording the deeds of coders; we’re architects of understanding, building bridges between complex systems and the humans who use them. That’s the true promise of docs-as-code, and it’s a future we must actively shape, one commit at a time.