A presentation at FOSDEM 2024 in in Brussels, Belgium by Lorna Jane Mitchell
Open Source DocOps Lorna Mitchell, Redocly @redocly ~ @lornajane ~ @lornajane@indieweb.social
What is DocOps? Documentation operations, allowing docs to be created, maintained and published collaboratively and in an efficient manner. @redocly ~ @lornajane ~ @lornajane@indieweb.social
Docs-as-code DocOps builds on Docs-as-code: •source control •text-based markup •continuous integration •local tools @redocly ~ @lornajane ~ @lornajane@indieweb.social
Open Source Open source means freedom. Open source also means: •not having to rebuild the same tools over again •run it where you want, CI, local •we collaborate to improve our shared tools •no vendor lock-in @redocly ~ @lornajane ~ @lornajane@indieweb.social
Tool the Docs @redocly ~ @lornajane ~ @lornajane@indieweb.social
Preview changes All documentation contributors should be able to see what they are doing. @redocly ~ @lornajane ~ @lornajane@indieweb.social
Link checking Automatically “click” every link and check it is valid. Check links in source or output format: •Source markup format (I use mlc) •An HTML link checker, run after build @redocly ~ @lornajane ~ @lornajane@indieweb.social
Link checking strategies The internet goes wrong sometimes. •restrict scope of checks (internal links, changed files) •weekly check all links for decay or other problems TIP: Someone else’s downtime should never block your build/release. @redocly ~ @lornajane ~ @lornajane@indieweb.social
Validation Check for syntax errors. Catches errors that aren’t visually obvious. The machines can help us! @redocly ~ @lornajane ~ @lornajane@indieweb.social
Validation tools Docs build tools may do this as standard. Or try: •Markdown: https://github.com/DavidAnson/markdownlint •ReStructuredText: Sphinx includes this feature •OpenAPI: https://github.com/Redocly/redocly-cli/ @redocly ~ @lornajane ~ @lornajane@indieweb.social
Formatting Valid is one thing, consistent and readable are another. Formatters adjust: •newlines and spacing •indentation •line length •bullet/table syntax @redocly ~ @lornajane ~ @lornajane@indieweb.social
Prose linting Quality assurance for the written word. Catch common mistakes with https://vale.sh •repeated words •correct case and spelling for product names •dictionary of your words •… and anything else you can think of @redocly ~ @lornajane ~ @lornajane@indieweb.social
Workflows and environments Make the tools work with your process. @redocly ~ @lornajane ~ @lornajane@indieweb.social
Source control branching GitHub flow: •small changes •each in their own branch •manageable to review @redocly ~ @lornajane ~ @lornajane@indieweb.social
Continuous integration Apply the tools to every pull request: •never miss running any check/test •build previews to assist reviewers Maintain documentation quality. @redocly ~ @lornajane ~ @lornajane@indieweb.social
Feedback loops Opening a pull request is a big feedback loop. We need small feedback loops: •all tools available locally •IDE integration a bonus (but avoid lock-in) •covered by setup docs @redocly ~ @lornajane ~ @lornajane@indieweb.social
Open Source DocOps Move fast and don’t break anything! @redocly ~ @lornajane ~ @lornajane@indieweb.social
Resources •https://lornajane.net •https://redocly.com •https://github.com/becheran/mlc •https://github.com/DavidAnson/markdownlint •https://github.com/Redocly/redocly-cli/ •https://vale.sh/ @redocly ~ @lornajane ~ @lornajane@indieweb.social
Every software project has a robust continuous integration/delivery setup, but many of our documentation projects are still playing catchup. In this talk you’ll hear about a selection of tools that are good additions to your documentation pipeline, and how to use them both locally and in CI. We’ll cover linting and validation of your source content, and look at tools that can help with consistent formatting. We’ll also look at content quality tools, such as prose linting, link checking, and more. You’ll see examples of projects that use some or all of these tools in anger, and we’ll also discuss when too many tools is too many! This session is recommended for anyone who works on documentation platforms as either writer or engineer, and wants to make their world better.
