Skip to main content

The Docs as Code Philosophy

· 3 min read
CoffeeCup
CoffeeCup
Senior Technical Writer

The Docs-as-Code Way: A Philosophy That Builds Better Docs​

For years, documentation happened only after development was finished. The method involved gathering information — sometimes straight from developers, but mostly within our own bubble, working among technical writers. Then one day, I realized something: I was using Git, writing in Markdown, pushing commits, editing in VS Code. Wait a minute — I was doing docs-as-code.

The Docs as Code Philosophy

🌤️ How I Discovered My “Twin” Philosophy of Docs and Code​

When I created my previous Coffee Cup website in early 2019, I wrote a page titled "Technical Writing" that opened with this line: "Technical Writing is the twin of Programming." Elsewhere on the page, I explained my idea further:

"The time where documentation was written apart from development, in separated departments, producing content in word processing tools is, or tends to be, over. (...) Documentation is the twin of Development, a helping and supporting twin."

At that time, I must admit I wasn’t aware of the “Docs as Code” concept — or even its philosophy. What I called a “twin” was my own version of it, shaped by experience and intuition. And yet, it led to a very practical implementation:

Use the same tools and steps to produce the documentation as you use to produce code. Documentation becomes part of the development workflow, and the technical writer is a member of the team.

🪢 Why the Twin Model Works​

Here are just a few benefits I’ve found working this way:

  1. The documentation phase isn't postponed until the last minutes before delivery.
  2. The technical writer isn't seen as an "MS Word" expert with interviewing skills (coder, PO).
  3. They use the same tools as the developers – which makes collaboration easier and faster.
  4. Developers often write the first draft; the technical writer rewrites, ennriches, pôlishes – focusing on content epxertise.
  5. The documentation is up-to-date and easy to maintain thanks to version control systems like Git that turns into a document management system.

This approach fosters real cooperation. And in that spirit, Markdown is the right syntax: a language shared across the team, keeping things structured without worrying about visual styling.

✍️ The Enduring Role of the Writer​

Of course, no matter how collaborative the tools or workflows get, the technical writer still plays a key role.

We ensure quality content, apply writing standards, add meaningful diagrams and visuals, define navigation structure, place links strategically, pick the right admonitions — and more. That’s our craft.

🪴 Thanks to everyone who developed this concept and helped it grow. As a technical writer, I’m grateful.