Document-as-Code | Concept and mechanics

Information we can work with

One maintained source can support more than one publication

A document is one useful view

A self-contained publication

  • Content, layout, and delivery together
  • Useful for reading and exchange
  • Shared passages may be copied

Maintained source information

  • Content has a clear owner
  • Outputs refer to shared sources
  • Presentation can vary by audience

Separate the source from its presentation

Reuse needs explicit selection and processing rules

  1. 01

    Maintain

    Procedure text and review metadata

  2. 02

    Select

    Choose content suitable for the audience

  3. 03

    Transform

    Apply an output template or calculation

  • Handbook
  • Website
  • Training material

A conceptual model, not a guarantee that every output updates automatically.

Markdown is one source format

People can read the text; tools can process the same file

  • Headings and lists express readable structure
  • Small text changes can be compared
  • Other information may need JSON, models, or media files

Recording is not the same as approving

Recorded history

  • What changed and when
  • Author and revision reference
  • A diff between versions

Review evidence

  • Who examined the change
  • Which revision they reviewed
  • Their decision and unresolved questions

Give software explicit fields

Procedure metadata answers questions that prose leaves implicit

  • id: PROC-003 identifies the item
  • owner: people-team identifies its maintainer
  • status: draft records its review state

Link information that must stay consistent

A policy change can identify related procedures for review

A security policy is referenced by access and equipment procedures, which are included in a handbook.
Illustrative source relationships, not task dependencies.

Make processing rules inspectable

Checks and transformations are maintained work too

  1. 01

    Read

    Load selected source files

  2. 02

    Check

    Validate fields and references

  3. 03

    Transform

    Assemble a view for its audience

  • Review queue
  • Handbook
  • AI context

A successful run establishes only what its configured checks cover.

Give AI relevant evidence, not just a prompt

A request alone

  • Draft a training guide
  • Unclear source revision
  • Unclear limits on proposed changes

Selected context

  • Reviewed access instructions
  • Audience and output requirements
  • Project rules and required checks

Try one complete information flow

Choose a source, a consumer, and one useful output

  • Name the owner and review responsibility
  • Try the source and metadata labs
  • Inspect the result and improve the rules