DevOps Your Docs

DevOps Your Docs Lorna Mitchell, Redocly @redocly ~ @lornajane ~ @lornajane@indieweb.social

@redocly ~ @lornajane ~ @lornajane@indieweb.social

Pre-requisites @redocly ~ @lornajane ~ @lornajane@indieweb.social

Content-as-code •Text-based markup enables coder tools •Separates content from presentation @redocly ~ @lornajane ~ @lornajane@indieweb.social

Git Best collaboration tool on the planet. •Full change history including user and date/time •Review all changes before publishing •Safely work on many different changes at once Has a learning curve. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Automation @redocly ~ @lornajane ~ @lornajane@indieweb.social

Automation @redocly ~ @lornajane ~ @lornajane@indieweb.social

How to Automate •Pick a tool you can run anywhere •Run it locally and configure settings •Add instructions and configuration to repo •Automate for every pull request @redocly ~ @lornajane ~ @lornajane@indieweb.social

Continuous integration •Check if there’s an existing integration •Or put your local command into the CI setup •Test it on a branch •Check it fails when you expect it to •Write down what was added, and why Sometimes called CI/CD Continuous Integration / Continuous Deployment @redocly ~ @lornajane ~ @lornajane@indieweb.social

GitHub Actions example Lint an API description in CI. name: API linting on: [pull_request] jobs: build: runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v4 - name: Set up node uses: actions/setup-node@v4 - name: Install Redocly CLI run: npm install -g @redocly/cli@latest - name: Run linting run: redocly lint openapi.yaml —format=github-actions @redocly ~ @lornajane ~ @lornajane@indieweb.social

Automation thinking •Error or warning? •No output means everything is fine •Document the tools used and their purpose •Never ignore a failing test @redocly ~ @lornajane ~ @lornajane@indieweb.social

DocOps tools •Link checking •Validation/formatting tools •Preview builds •Vale @redocly ~ @lornajane ~ @lornajane@indieweb.social

Check links Either check source format, or HTML output. Check only your own links •Why? In case another site breaks. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Validation/Formatting Consistent whitespace and layout lowers cognitive load. Choose whether to: •validate, and report problems •format, automatically Use tools/config that work locally and in CI. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Preview builds Every pull request should build a preview. •makes sure that the site builds in the cloud •useful to share with stakeholders •also handy for quick reviews if needed •avoids surprises @redocly ~ @lornajane ~ @lornajane@indieweb.social

Vale Quality assurance for the written word. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Vale Use Vale or another prose linting tool to: •check spellings (and common mis-spellings) •check product names and Proper Nouns (TM) •identify repeated words, latin terms, etc •substitutions •title/sentence case in headings •… and much more @redocly ~ @lornajane ~ @lornajane@indieweb.social

Invest time and energy @redocly ~ @lornajane ~ @lornajane@indieweb.social

Local platform All tools should be available locally for fast feedback. @redocly ~ @lornajane ~ @lornajane@indieweb.social

People matter Docs as code is about documentarian efficiency. •Invest in the skills of the team. •Identify and share resources. •Set aside time for hands-on practice. @redocly ~ @lornajane ~ @lornajane@indieweb.social

Resources •https://lornajane.net/ •https://redocly.com/ •https://www.writethedocs.org/ •https://www.docslikecode.com/ •https://vale.sh/ @redocly ~ @lornajane ~ @lornajane@indieweb.social