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