Docs As Code, for Coders

A presentation at TechMids in October 2023 in Birmingham, UK by Lorna Jane Mitchell

Docs-as-code, for Coders Lorna Mitchell, Redocly @redocly ~ @lornajane

What is Docs-as-code? Manage documentation using coder tools @redocly ~ @lornajane

Benefits of docs-as-code •Changes can be made quickly and simultaneously •Powerful collaboration and review tools •Single source of truth •Separation of content and presentation •Audit trail @redocly ~ @lornajane

Programmers have the best tools @redocly ~ @lornajane

Toolbox •Editors with syntax support •Local preview •Source control •Linting/formatting •CI/Pull request workflow @redocly ~ @lornajane

DocOps: Code + words @redocly ~ @lornajane

Markdown / Markdoc ## One large file to many small ones OpenAPI is designed with support for $ref syntax, allowing parts of an API desc If you have one large single file, split it up like this: redocly split openapi.yaml --outDir myApi The original file is unchanged, but look in the directory named by the --outDir * An openapi.yaml file, which is the entry point of the API and includes the i * Apaths/` directory, with a file for each of the URLs in the API. All verbs fo @redocly ~ @lornajane

ReStructuredText Stats ===== redocly stats discourse.yaml Lint ==== redocly lint discourse.json --extends=minimal --format=summary Then add max-problems=200 Minimal rules: https://redocly.com/docs/cli/rules/minimal/ @redocly ~ @lornajane

AsciiDoc
A selection of endpoints with specific behaviours at http://httpbin.org/[httpb Register your own endpoint at http://requestb.in and use it in place of http://re [[curl]] ==== Command Line HTTP http://curl.haxx.se[Curl] is a command-line tool available on all platforms. In its most basic form, a Curl request can be made like this: —-curl http://requestb.in/example —-@redocly ~ @lornajane It

QA for prose In CI, and locally: •Validate the markup •Use a prose linter such as Vale https://vale.sh/ •Check links •Build output preview @redocly ~ @lornajane

Pull request workflow Everything you know about good pull request practice? Do that. @redocly ~ @lornajane

Git and writers Help others adopt the workflow: •Find tools and resources that work for them •Be prepared to provide a lot of support Experts of other disciplines may learn or work differently @redocly ~ @lornajane

Developers and Docs @redocly ~ @lornajane

Audience and goals WHO are you writing for? WHAT will they gain? @redocly ~ @lornajane

Outline before writing Preparation makes the process easier @redocly ~ @lornajane

Content types From https://diataxis.fr: •Concept •Task •Tutorial •Reference @redocly ~ @lornajane

Docs and Coders Engineering is about solving problems and helping people. So is documentation. @redocly ~ @lornajane

Resources •https://lornajane.net •https://redocly.com •https://idratherbewriting.com/ •https://docsfordevelopers.com/ @redocly ~ @lornajane

Lorna Jane Mitchell
@lornajane

1 / 18

Resources

The following resources were mentioned during the presentation or are useful additional information.