Cynthia Ng @arty-chan May 8, 2023 Write the Docs Portland Docs as Code: Automation the Developer way

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

For more about making your ideas stick with others, check out our book! Docs as Code

“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/

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

For more about making your ideas stick with others, check out our book! Automated Checks

Docs Pipeline

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

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

Example Report

Example Warning

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!

For more about making your ideas stick with others, check out our book! Thank you Cynthia Ng Arty-chan@Slack TheRealArty@Twitter [email protected]