Instruction flows

An instruction flow turns a choose-your-own-adventure install guide into a menu-driven path: one decision at a time, then only the steps that follow.

In plain language: navigate by the content itself.

Core claim

When documentation is really a decision tree (OS, install method, package manager, CI flavor), do not dump every branch on one page and do not exile long branches to tangent articles. Present orthogonal choices as buttons, insert the chosen subflow as a continuation, and keep other options available so readers can rewind.

Why it exists

Linear install pages either explode into every platform variant or hide important paths behind “oh by the way” links. Both force readers to hold the real tree in working memory — the same cognitive tax progressive disclosure refuses elsewhere.

Instruction flows merge navigation and content for the wizard-shaped part of a page. The rest of the article can stay ordinary prose.

Anatomy

  • Decision — short prompt plus option buttons (inline when labels are short)

  • Continuation — steps revealed under the chosen option (nested decisions allowed)

  • Path state — breadcrumb of choices; shareable URL variables

  • Expand / print — optional kitchen-sink mode for printing or scraping

  • Skeleton — prefer keeping branches in the DOM (hidden) so SEO and AI still see the graph; add lazy loading only when size forces it

Design rules

  1. Order decisions by contextual dependency (environment first, optional methods later)

  2. Offer short implications on each option; link out for deep comparisons

  3. Prefer continuations over tangent pages for the same job

  4. Leave unchosen options visible so users can try another path

  5. Encode the path in the URL when the combination is worth sharing

  6. Keep a master expanded mode for print — do not make the default view the kitchen sink

Antora / Asciidoctor

Implementation lives in the sibling org as @antora-supplemental/instruction-flow (repository asciidoc-interactive).

  • Asciidoctor block style instructionflow on example blocks (====) with a JSON5 graph (start, nodes, choice / content)

  • Embedded CSS + client script (self-contained pages)

  • Query parameter iflow_<flow-id>=optionId1,optionId2,…​ for shareable links

  • Toolbar: Back, Start over, Expand all for print

This docs site registers that extension so the live example below is real Antora output — not a mock.

Use Back and Start over to try another path. The URL query string stores choices (for example iflow_install-sample=linux,cli,pnpm).

Roadmap (extension)

Planned authoring layers on the same runtime — not blockers for embedding today:

  • Inline choice macros ([npm][pnpm]…)

  • AsciiDoc-native nested list / role syntax (less raw JSON5)

  • Lazy-loaded branches for huge graphs

  • Analytics events on each choice

  • Optional full-site mode that mirrors or replaces the nav tree

See the package roadmap in asciidoc-interactive.

Prototype