Documentation Workflows
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.
From Git-based static site generators to collaborative WYSIWYG editors, your workflow determines how content is created, reviewed, published and maintained.
Broadly speaking, there are two types of documentation workflow:
Your particular workflow doesn't need to align 100% to one of these definitions.
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 |
If you want to learn more about docs-as-code, you can start from this beginner-friendly article.
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.