Docs as Code - The New Way of Creating Documentation

In this blog issue, you will learn some basic insights into the philosophies of technical writing, as well as insights made by specialists and experts in this area of writing. What do technical writers do? Quoting from T. R. Girill’s paper on “Philosophy's Relevance to Technical Writing,” we can say that “Technical writers prepare research reports, proposals, instruction books, and newsletters for medical centers, manufacturing firms, financial institutions, and government laboratories.” Of course, this represents only a small area of use cases for technical writers, and there are many more you can imagine. Let’s first concentrate on the technical writing of handbooks. Ryan Brong makes this point clear on his blog “Ryan Brong’s ePortfolio”, where he writes that engineers and scientific researchers need to bring their ideas to the public by using great technical communication.

Many businesses and sectors rely on technical writing for essential communication. Simplifying complexity, technical writing enables clear understanding and implementation of ideas, theories, practices, or procedures.

It holds immense relevance for businesses and sectors employing user documentation, instructions, technical reports, feasibility studies, corporate reports, research results, policies and procedures, business plans, white papers, case studies, literature reviews, proposals, and more.

Technical writing, present since the inception of written languages, is experiencing rapid growth, particularly in our advancing era of telecommunications. Its popularity shows no signs of waning and will remain integral to our world for decades to come.

---

So, What Does That Mean, and How Does This Work?

Technical writing simplifies complex ideas, making them easy to understand and implement in different contexts such as user documentation, reports, studies, and plans.

Essentially, technical writing involves conveying technical information clearly and effectively. It ensures that complex concepts are presented in a manner that is accessible to the intended audience. This can involve breaking down intricate processes, explaining specialized terminology, and providing clear instructions.

In practical terms, technical writers analyze the audience, gather relevant information, organize content logically, and communicate it using appropriate language and formats. They strive to make technical content understandable and usable for readers who may not have a technical background.

Overall, technical writing plays a crucial role in facilitating communication and knowledge transfer within businesses, industries, and sectors, ensuring that information is conveyed accurately and comprehensively.

There Are 5 Components of Technical Writing

The components of technical writing are fundamental for creating effective communication materials. They include:

1. Purpose: Clearly defining the reason for the document and what it aims to achieve.
2. Target Audience: Identifying the intended readership and understanding their knowledge level and needs.
3. Content: Providing accurate and relevant information to fulfill the document’s purpose and meet the audience’s requirements.
4. Organization: Structuring the content logically and coherently to facilitate understanding and navigation.
5. Style: Using appropriate language, tone, and formatting conventions to enhance readability and convey information effectively.

There Are 7 Types of Technical Writing

As for the types of technical writing, they encompass a range of documents tailored to different purposes and audiences. They include:

1. User Manuals: Instructions and guides for using products or systems.
2. Standard Operating Procedures (SOPs): Detailed instructions for performing specific tasks or operations.
3. Technical Reports: Documents presenting findings, analysis, and conclusions from research or investigations.
4. White Papers: Authoritative reports addressing complex issues, often used for business or technical purposes.
5. Proposals: Formal documents proposing solutions, projects, or collaborations.
6. Online Help Documentation: Digital guides and resources to assist users with software applications or websites.
7. Scientific Articles: Papers presenting research findings and analysis within the scientific community.

An example of technical writing could be a user manual for a smartphone, providing step-by-step instructions on how to set up, operate, and troubleshoot the device. Such documents aim to empower users with the knowledge needed to use the product effectively and efficiently.

Technical writers face several disadvantages. Firstly, tracking changes in purely text-based programs can be challenging as they lack integrated versioning features. Secondly, automated tests to identify and fix documentation errors early are absent. Thirdly, organizing and reusing content in purely text-based environments can be cumbersome, leading to inconsistencies. Fourthly, deploying updates is slower without integrated processes to automatically publish changes. Lastly, achieving automation and efficiency in the publishing processes is not straightforward.

---

The Solution for Technical Writing is Docs as Code

“Docs as Code” represents the optimal method for creating technical documentation. The documents are coded within an application, enabling users to utilize the content, format it, maintain it, and distribute it across various devices and mediums.

“Docs as code” is a methodology that treats documentation as an integral part of the software development process, rather than an afterthought or a separate task. It applies principles and practices from software development to the creation, review, and maintenance of documentation.

Here are some key aspects and benefits of the “docs as code” approach:

1. Version Control: Just like source code, documentation is stored in version control systems such as Git. This allows for tracking changes, collaboration among team members, and reverting to previous versions if needed.
2. Text-Based Format: Documentation is often written in plain text or lightweight markup languages like AsciiDoc, Markdown or reStructuredText. These formats are easy to read and write, and they can be converted to various output formats such as HTML, PDF, or EPUB using tools like Sphinx, MkDocs, or GitBook.
3. Automation: Continuous integration (CI) and continuous delivery (CD) pipelines can be set up to automatically build and deploy documentation whenever changes are made to the documentation repository or the codebase. This ensures that the documentation is always up-to-date and in sync with the software.
4. Collaboration: Since documentation is stored alongside code in the same repository, developers and technical writers can collaborate more closely. They can review each other’s work, provide feedback, and make changes together, fostering better communication and shared understanding.
5. Reusability: Documentation components such as code snippets, configuration examples, and troubleshooting guides can be reused across different projects or modules. This reduces duplication of effort and ensures consistency in documentation style and content.
6. Testing: Just like software, documentation can be tested to ensure accuracy, completeness, and readability. Automated tests can be written to validate links, code samples, and other aspects of the documentation.
7. Feedback Loop: By treating documentation as code, developers are more likely to engage with it actively. They can suggest improvements, report errors, or request clarification directly through the same channels they use for code contributions, such as pull requests and issue trackers.
8. Agility: Adopting a “docs as code” approach allows teams to iterate on documentation quickly and respond to changes in the software or user feedback more effectively. It promotes an agile mindset where documentation evolves alongside the codebase.

In summary, “docs as code” promotes a culture where documentation is valued as a first-class citizen of the software development process. By applying principles of version control, automation, collaboration, and testing to documentation, teams can create and maintain high-quality documentation that enhances the overall user experience and developer productivity.

Can I Use Docs as Code for Other Technical Writing?

Yes, the principles and practices of “docs as code” can be applied to various forms of technical writing beyond traditional software documentation. Here are some examples:

1. API Documentation: Just like software documentation, API documentation benefits from version control, collaboration, and automation. With “docs as code,” API documentation can be stored alongside the codebase, ensuring that it remains accurate and up-to-date with each software release.
2. System Documentation: Documentation for systems, architectures, and infrastructures can also be treated as code. This includes network diagrams, system configurations, deployment procedures, and operational runbooks. Storing this documentation in version control allows teams to track changes and ensure consistency across environments.
3. Technical Guides and Tutorials: Guides and tutorials that explain how to use software tools, frameworks, or libraries can benefit from the “docs as code” approach. By storing them in a text-based format and leveraging automation tools, authors can quickly update and publish guides to reflect changes in the technology landscape.
4. Training Materials: Training materials for onboarding new team members or educating users on how to use a product can be managed as code. By treating training materials as part of the documentation ecosystem, organizations can maintain a single source of truth for all instructional content and ensure that it remains relevant and accessible.
5. Compliance and Regulatory Documentation: Documentation related to compliance requirements, such as security policies, data privacy regulations, and industry standards, can be managed using the “docs as code” approach. Storing compliance documentation in version control helps organizations track changes and demonstrate adherence to regulatory requirements.
6. Internal Knowledge Bases: Internal knowledge bases, wikis, and documentation repositories can benefit from being managed as code. By storing knowledge base articles and internal documentation alongside the codebase, organizations can ensure that tribal knowledge is captured and accessible to team members, regardless of turnover or organizational changes.
7. Configuration Management: Documentation related to system configurations, environment setups, and infrastructure provisioning can be managed as code using tools like Terraform, Ansible, or Puppet. Storing configuration documentation alongside infrastructure code ensures that changes are tracked, reviewed, and documented in a consistent manner.

In summary, the “docs as code” approach is not limited to software documentation but can be extended to various forms of technical writing and knowledge management. By applying version control, automation, collaboration, and testing to technical documentation, organizations can improve documentation quality, maintainability, and accessibility across different domains and disciplines.

Docs as Code Versus Microsoft Word

Working with Office file formats like Microsoft Word allows users to locally edit, print, and share documents via email or file storage with other authors. Depending on the infrastructure, documents can be collaboratively edited via SharePoint or OneDrive. However, it becomes challenging, especially when different edited document versions need to be merged across organizational boundaries. An alternative to this approach is using wikis, where authors collaborate on documents. The process of formatting content into print-ready documents with attractive layouts is often cumbersome. Both approaches reach their limits when writers are required to maintain different versions of documents concurrently, for example, for different releases or products.

For newcomers in technical writing using such systems, several platforms have evolved over time. Markdown, AsciiDoc, and reStructuredText are just a few examples. They offer several advantages, as they are readable and editable in any text editor. Through conversion, content from the source texts can be transformed into other formats, such as high-quality HTML or PDF documents. They include various components such as headings, cross-references, and tables of contents. In contrast to traditional word processing, transitioning to such a format requires a different approach to document management. Check out our blog post on creating a user manual in AsciiDoc for a practical example.

Docs-as-Code for Writers, Not Developers

Here’s the uncomfortable truth about docs-as-code: the methodology was designed by developers, for developers. And for many technical writers, adopting it feels like being asked to become a software engineer just to write documentation.

Reddit is full of writers sharing this frustration: “New to docs as code and hating it”, “I spend more time staring at VS Code than writing”, “Modern tech writing forces us to use tools designed for another job entirely.”

They’re not wrong. A traditional docs-as-code setup looks like this:

1. Install a code editor (VS Code, Atom, Sublime)
2. Install a package manager (npm, pip, Homebrew)
3. Install a static site generator (MkDocs, Docusaurus, Jekyll, Hugo)
4. Configure YAML files, build scripts, and folder structures
5. Learn Git commands in the terminal
6. Set up CI/CD pipelines for publishing
7. Finally start writing

That’s a lot of overhead before you type a single word of documentation. And every one of those tools requires maintenance, updates, and troubleshooting when something breaks.

The Alternative: Docs-as-Code Without the Pain

What if you could get all the benefits of docs-as-code without the developer tooling? That’s exactly what adoc Studio delivers:

• No terminal required. Write, preview, and export from a native app.
• No build scripts. Click Export for professional PDF, HTML, and websites.
• No package managers. No npm install, no pip, no dependency hell.
• Git built in. Version control without memorizing command-line syntax.
• Live preview. See your formatted document as you write, not after a build step.

You still get everything that makes docs-as-code valuable: plain-text files, version control, content reuse, and multi-format output. You just don’t need a computer science degree to use it.

Who Is This For?

• Word/Flare users who know docs-as-code is the future but are intimidated by the tooling
• Technical writers in developer-heavy teams who want to work in Git without living in the terminal
• Documentation managers looking for a docs-as-code solution that writers will actually adopt
• Solo authors who want professional output without maintaining a build pipeline

From Word to Docs-as-Code: A Practical Path

If you’re currently using Microsoft Word or a similar WYSIWYG editor, here’s a realistic migration path:

1. Start with one document. Pick a single guide or manual to convert. Don’t try to migrate everything at once.
2. Convert to AsciiDoc. Use Pandoc to convert your .docx file: pandoc document.docx -t asciidoc -o document.adoc
3. Open in adoc Studio. See your content with live preview. Clean up formatting as needed.
4. Learn AsciiDoc incrementally. Start with headings, lists, and bold/italic. Add tables, images, and code blocks as you need them.
5. Set up Git when you’re ready. adoc Studio’s built-in Git support makes this painless. No terminal required.
6. Export and compare. Generate a PDF from adoc Studio and compare it with your Word output. The quality difference speaks for itself.

The key insight: you don’t have to adopt everything at once. Docs-as-code is a spectrum, not a switch. Start writing in AsciiDoc, add version control later, and build automation only when you need it.

For a step-by-step migration walkthrough including Pandoc commands and a clean-up checklist, read our full Word to Docs-as-Code guide.

A Concrete Docs-as-Code Stack

“Docs-as-code” is a methodology, not a product. The actual stack you pick depends on team size, developer skills, and how much automation you want to maintain. Here are three concrete setups that work in production today.

Stack 1: Solo Writer or Small Team

Layer	Tool
Editor	adoc Studio
Versioning	Git via adoc Studio (or iCloud for the first weeks)
Build & Publish	One-click static site export from adoc Studio
Hosting	GitHub Pages, Netlify, or any static host

This stack gets you writing in minutes. No build server, no YAML, no plugin maintenance. Add Git when you’re ready, not on day one.

Stack 2: Developer-Heavy Team

Layer	Tool
Editor	VS Code with the AsciiDoc extension, or adoc Studio for non-devs
Versioning	Git on GitHub or GitLab
Build & Publish	Antora or Asciidoctor in GitLab CI / GitHub Actions
Hosting	GitLab Pages, GitHub Pages, or internal CDN

Best when developers and writers share the same repo and the docs site needs versioning per release. Antora is the standard choice for multi-repo, multi-version documentation.

Stack 3: Enterprise

Layer	Tool
Editor	adoc Studio Pro for writers, VS Code for engineers
Versioning	Self-hosted Git (GitHub Enterprise, GitLab, Bitbucket)
Build & Publish	GitHub Actions or Jenkins, with PDF/UA validation
Hosting	Internal CDN, S3 + CloudFront, or a private docs portal

This setup adds compliance touchpoints: PDF/UA validation, role-based reviews, and audit logs. The writing experience for the actual editors stays the same.

A Real Repository Layout

A typical AsciiDoc-based docs repository keeps content, includes, and assets in clearly separated folders:

attributes.adoc defines reusable variables like product name and version. _includes/ holds the small building blocks that appear in multiple pages: legal disclaimers, glossary entries, callouts. Anything binary like screenshots lives next to the content, never inline. Once your team agrees on the layout, every new page is just one more file in the right folder.

Automating the Build with CI

Once your docs live in Git, you can build and deploy them on every commit. Here’s a minimal GitHub Actions workflow that publishes an HTML site to GitHub Pages on each push to main:

Your docs are now always in sync with the repository. No more “I forgot to upload the new PDF” moments. The same pipeline can produce a PDF artifact in parallel for offline distribution.

FAQ: Common Docs-as-Code Concerns

Do I need to know Git to use docs-as-code?
No. You can start in adoc Studio without Git at all and still get the structural benefits of AsciiDoc. Add Git later, when collaboration or audit history becomes a real need. adoc Studio’s built-in Git support makes the transition painless.

What if my SMEs don’t use the terminal?
They don’t have to. Pull requests can be reviewed in the browser on GitHub or GitLab. SMEs comment inline and suggest changes in plain text, with no terminal involved. Many teams find that engineers actually prefer this over fighting with Word’s track changes.

How do I handle screenshots and binary assets?
Store them next to the content in an images/ folder and reference them with a relative path. AsciiDoc keeps the binary out of the source file, so diffs stay readable. See our deep dive on images in docs-as-code for the full pattern.

Can I still produce print-ready PDFs?
Yes. adoc Studio exports PDF directly from the editor, and the same source can be styled with CSS for HTML or with a PDF theme for print. The Pro Edition adds PDF/UA-compliant export for accessible documents.

Let’s Talk AsciiDoc

AsciiDoc is well-suited for technical writing in Docs as Code due to its clear, structured, and easily understandable syntax, which is particularly suitable for documenting software projects. With its simple Markdown-like formatting, developers and technical writers can effortlessly compose complex concepts, code examples, diagrams, and instructions while maintaining a clear separation of content and formatting.

AsciiDoc also supports integration with version control systems like Git, facilitating seamless collaboration and version control. Additionally, it offers a variety of extensions and integrations for automated document generation in various formats such as HTML, PDF, and ePub. Overall, AsciiDoc provides a flexible and powerful platform for creating and managing technical documentation within the realm of Docs as Code.

AsciiDoc with adoc Studio

The downside of AsciiDoc is that if you are not a tech-savvy person and simply want to focus on writing, you still end up spending a lot of time in a code environment. However, there’s a great solution available to address this issue. It allows you to compose your technical documents with AsciiDoc on your Apple devices, whether it’s a Mac, iPad, or even iPhone.

You can apply all attributes from the AsciiDoc syntax and simultaneously see the result in real-time. Afterwards, you can style the document’s appearance and export the content in various formats. Be sure to check out adoc Studio if you are serious about technical documentation using the AsciiDoc language.