Docs as Code: Automation the Developer way

Created for 5 minute lightning talk at Write the Docs 2023 https://www.writethedocs.org/conf/portland/2023/

--

We want to make reviews more efficient, and use the tools developers are used to. When documentation is treated like code by everyone, we can start using tooling designed for code and adapt it for docs! We’ll talk about how we can integrate the use of linters (namely markdownlint, and Vale), linter validations with Continuous Integration (CI) pipelines, even code quality to analyze the quality of contributions, and automation that can suggest the ideal reviewers.

Full script at https://cynthiang.ca/2023/05/09/write-the-docs-2023-lightning-talk-docs-as-code-automation-the-developer-way/

Transcript

1. Cynthia Ng @arty-chan May 8, 2023 Write the Docs Portland Docs as Code: Automation the Developer way
2. File:Tanuki in Higashiyama Zoo - 2.jpg. (2022, November 29). Wikimedia Commons. Retrieved 22:49, April 14, 2023 from https://commons.wikimedia.org/w/index.php?title=File:Tanuki_in_Higashiyama_Zoo_-_2.jpg CC-BY-SA 4.0 International
3. For more about making your ideas stick with others, check out our book! Docs as Code
4. “Documentation as Code (Docs as Code) refers to a philosophy that you should be writing documentation with the same tools as code [and using] the same workflows as development teams”. - Write the Docs https://www.writethedocs.org/guide/docs-as-code/
5. The Flow Docs with Development Part of the “definition of done”. New content for features and updates for bugs. Automated Checks Metadata Formatting: markdownlint Style guide: Vale Accessibility Reading level Repository + Changes Get a copy. Make changes to Markdown files. Commit changes. Issue Feature or bug. Code, docs, or both. Review Include Technical Writer. Merge Publish
6. For more about making your ideas stick with others, check out our book! Automated Checks
7. Docs Pipeline
8. The Pipeline Jobs (Part 1) UI Links Checks for broken links to docs from the product. Links Checks for broken internal links and anchors. Danger review Checks for adherence to review process. Such as: - Add Technical Writer for docs. https://docs.gitlab.com/ee/development/documentation/testing.html
9. The Pipeline Jobs (Part 2) markdownlint + Vale Checks adherence to style guide. Fails on rule violation or “error”. Such as: - Lists - Future tense “Code” Quality Report on content that triggered a “warning”. Such as: - Word choice - Spelling Accessibility Integrated into other jobs. Such as: - Heading structure - Reading level https://docs.gitlab.com/ee/development/documentation/testing.html
10. Example Report
11. Example Warning
12. Benefits • Consistency • Less human errors • Efficiency • Increased self-service • Improved feedback cycle • Familiarity • Reusability with other projects • and all the other benefits from automated testing!
13. For more about making your ideas stick with others, check out our book! Thank you Cynthia Ng Arty-chan@Slack TheRealArty@Twitter artychan@mastodon.social