An introduction based on the living tutorial

Document-as-Code

Maintain the knowledge. Shape the view.

One source. Several useful views.

Maintain information around the people responsible for it. Present it around the reader's needs.

  • Instructions become a handbook or a training excerpt.
  • Metadata reveals what needs attention.
  • Shared sources provide context for AI-assisted work.
The fictional onboarding dataset contains two approved procedures and one draft.
Chapter 1's fictional onboarding example. Not tutorial approval data.

Bring the process into the workspace.

Application-led work

  • Content lives in documents and applications.
  • Changes to tools may depend on another team.
  • Publishing follows each application's process.

Repository-led work

  • Sources and processing rules live together.
  • Teams can develop their tools within agreed boundaries.
  • Checks and publishing are versioned alongside content.

A proposal becomes shared information.

Keep the current version available while the team prepares and reviews a change.

  1. 01

    Branch

    Prepare the change.

  2. 02

    Commit

    Record the proposal.

  3. 03

    Pull request

    Inspect the diff and build.

  4. 04

    Review

    Check meaning and effects.

  5. 05

    Merge

    Update the shared source.

Required review and checks depend on repository rules.

Recording is not approving.

A review decision needs a scope, an identified version, and a responsible reviewer.

  • A commit records what the files contained.
  • Accepting a change updates the shared source.
  • Approving a publication covers a particular deliverable.

Adapt the view. Keep the facts connected.

A presentation is not a handbook divided into slides.

  1. 01

    Shared sources

    Markdown, metadata, and visuals.

  2. 02

    Select and adapt

    Choose the audience, scope, and sequence.

  3. 03

    Check the output

    Review meaning, completeness, and presentation.

  • Website
  • PDF handbook
  • Training presentation

These are publication choices, not three automatically implemented export pipelines.

Make repeatable work repeatable.

Astro builds the reading experience. GitHub Actions runs the process. GitHub Pages hosts the result.

  • A pull request checks that the website builds.
  • Updates to main trigger the publishing workflow.
  • A successful build does not establish content approval.

Start with one information item.

Choose something you maintain today. Give it an owner, a review process, and two useful views.

  • Keep the maintained facts in one source.
  • Use AI to help develop and check the connections.
  • Improve the process as the team's needs change.