Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Docs as Code: Automation the Developer way

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/

Cynthia "Arty" Ng

May 09, 2023
Tweet

More Decks by Cynthia "Arty" Ng

Other Decks in Technology

Transcript

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

    View Slide

  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

    View Slide

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

    View Slide

  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/

    View Slide

  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

    View Slide

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

    View Slide

  7. Docs Pipeline

    View Slide

  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

    View Slide

  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

    View Slide

  10. Example Report

    View Slide

  11. Example Warning

    View Slide

  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!

    View Slide

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

    View Slide