A presentation at WriteTheDocs Atlantic by Lorna Jane Mitchell
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
Take the tools of software development, the process and culture obsession of operations, and apply the resulting mixture to your documentation. In this talk we’ll cover how modern software practices are lending themselves to documentation projects, and how you can add these ingredients to your own projects. To collaborate safely across complex projects, use source control and gain the side benefits of clear changesets with attribution. To ensure the finished product is up to scratch, automate quality checks such as link checking, validation and formatting. To empower all contributors to work efficiently, invest time and effort in their skillsets and the tools they use, as well as in the CI pipeline. Bring the best bits of modern technology to your pipeline and learn how to DevOps your documentation; this talk is ideal for writers of all levels, and project leads.
