---
title: Documentation Workflows
slug: books/technical-writing/documentation-workflows
icon: 💻
createdAt: 2025-04-29T17:04:01.617Z
---

Choosing a documentation workflow isn't just about process - it's about shaping the entire toolchain. Sometimes *you* won't get a choice, but just know that the way you or your team approach documentation directly influence the technologies you use.&#x20;

From Git-based static site generators to collaborative WYSIWYG editors, your workflow determines **how content is created**, **reviewed**, **published** and **maintained**. &#x20;

Broadly speaking, there are two types of documentation workflow:

:::DropList
```json
{
  "columns": [
    {
      "id": "1",
      "name": "📜 ",
      "items": [
        {
          "id": "eQhdFpPi_cfAbDbH9RfLr",
          "content": "Traditional documentation",
          "justAdded": false
        },
        {
          "id": "dvGSp2YMEC3W5uLDE661_",
          "content": "A content-focused approach using WYSIWYG tools and separate publishing workflows. It prioritizes ease of use and polished output, often maintained by dedicated documentation teams.",
          "justAdded": false
        }
      ]
    },
    {
      "id": "3",
      "name": "💻",
      "items": [
        {
          "id": "s3oiUmIRrPCWxx8Zx-RYR",
          "content": "Docs as code",
          "justAdded": false
        },
        {
          "id": "pP-S3Sqca8ZqjS8dWwNir",
          "content": "A developer-centric workflow where documentation is written in plain text, versioned with Git, and integrated into the software delivery pipeline. It emphasizes automation, collaboration, and treating docs like code.",
          "justAdded": false
        }
      ]
    }
  ]
}
```
:::

:::hint{type="info"}
Your particular workflow doesn't need to align 100% to one of these definitions.&#x20;

For example, you could author in a tool like MadCap Flare or oXygen, which are based on HTML or XML files (but not Markdown), and yet have the documentation integrated into the software delivery pipeline.
:::

This table shows a high-level comparison of the two approaches.

| **Aspect**         | **Docs as Code**                                             | **Traditional Documentation**                            |
| ------------------ | ------------------------------------------------------------ | -------------------------------------------------------- |
| **Tooling**        | Git, Markdown, static site generators (e.g., Sphinx, MkDocs) | Word, Google Docs, SharePoint                            |
| **Format**         | Plain text (Markdown, AsciiDoc, reStructuredText)            | Rich text formats (.docx, HTML in WYSIWYG)               |
| **Workflow**       | Pull requests, branches, code reviews                        | Email approvals, manual edits, centralized review        |
| **Publishing**     | CI/CD pipelines, automated deployment                        | Manual publishing, uploading to intranet or PDF export   |
| **Versioning**     | Git-based, tied to code versions                             | Often ad hoc or based on manually tracked versions       |
| **Collaboration**  | Developers and writers collaborate in same repos             | Writers work separately; developers may not see docs     |
| **Audience Fit**   | Ideal for developer-centric content and APIs                 | Better for policy, compliance or non-technical audiences |
| **Maintenance**    | Continuous updates, co-evolves with code                     | Periodic updates, can easily get outdated                |
| **Review Process** | Integrated with code review (e.g., GitHub PRs)               | Document-specific workflows, approval chains             |
| **Access Control** | Repo-based permissions, open or private                      | Often restricted, siloed by department or role           |

:::hint{type="success"}
If you want to learn more about docs-as-code, you can start from [this beginner-friendly article](https://deborahwrites.com/blog/docs-like-code-basic-intro/).
:::

The following section serve as an overview of tools and technologies frequently used in technical writing, and they should help you make the best choice for your team.
