Open Source DocOps

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