Documentation as Code, Where to Start?
summary
Advocates treating documentation as code by writing docs in plain text so sources remain readable and editable, using Asciidoc with Asciidoctor for authoring and rendering. Recommends Asciidoctor.js live preview (browser or IDE plugins) to generate HTML/PDF instantly, Antora to aggregate multiple repositories into a publishable site, using git for review and Asciidoc features (headings, lists, admonitions, inclusions); notes production styling still requires HTML/CSS work.
AI-written summary · about
chapters (12)
- 0:00Introduction
- 1:41Lightweight doc syntaxes
- 3:25Asciidoc overview
- 4:32Asciidoc heading hierarchy
- 6:58Writing and organizing ideas
- 12:20Git collaboration
- 14:53Publish PDF or HTML
- 17:46Automated publishing pipelines
- 20:16Writing first drafts
- 21:40Avoiding tables in docs
- 22:42Customizing outputs
- 23:23Bonus: Macros and includes
related talks
51mDocumentation as Code (Explained to My Father)
50mContinuous and Automated Documentation Docs As Code in Practice
47mDocumentation as code (explained to my dad)
41mStop making fool of yourself about documentation
46mAsciidoctor: because writing docs does not have to suck
35mThe practical implementation of Documentation as Code
45mDocs as Code Fix a poor documentation culture in your organization
51mGetting started with Asciidoctor