Key points in this video

The documentation workflow usualy takes one of these approaches:

• The manual approach, where processes are handled by humans. You get higher-quality docs and more freedom, but it's slower, involves more work, and easier to make mistakes in.
• The automated approach, where processes are automated. It's faster, involves less work, and can lead to less mistakes, but it can be restrictive and lead to docs that are optimised for machines. There's also work to be done in maintaining the tools.
• The hybrid approach, a combination of manual and automated. Most things are automated, with human oversight to fill in the gaps. Easier, faster workflow and potentially higher quality docs, but also more work in figuring out the integration of manual and automated.

Docs-as-code is a kind of hybrid approach that applies the workflows and tools we use for code to documentation, including things like storing the raw docs in a repository and editing with a text editor, using version control, code review, automation and Continuous Integration.

Some good reasons to go docs-as-code:

• Fits into the engineering workflow, so helps promote good documentation habits amongst engineers
• Easier for docs to live next to code
• All the benefits of version control: diffs, changelogs, pull requests, history, rollback, branches...
• All the benefits of code review: less errors, consistent style
• All the benefits of automation: reduce work, identify problems, custom tools to improve processes/output
• Greater control/customisation (for instance, localisation, integrating with company site)

When setting up a docs-as-code workflow, keep things simple, and don’t force it.

Regardless of the approach chosen, there needs to be a commitment to producing good docs..