Document-as-Code: Rethinking How We Work with Information
Speaker notes · Suggested session length: 15 minutes
Launch the presentation · Tutorial home
1. Information we can work with
Ask the audience where the same instruction appears in their work. A handbook, training guide, and website may each contain a copy. This session explores a different arrangement: maintain the information deliberately, then select and present it for each audience. It is not a requirement to use GitHub or Markdown.
2. A document is one useful view
Do not portray word processors as incapable of automation or structured content. The distinction is how a team organizes its maintained sources and outputs. Self-contained documents remain valuable delivery formats. The question is where updates are made and how repeated information stays consistent.
Chapter 1: Document-as-Code: Information We Can Work With · Chapter 10: Automating Information with GitHub Actions
3. Separate the source from its presentation
Use the fictional onboarding example. Contacts remains draft, so a rule including it would produce a review copy, not a finished handbook. Review and processing can repeat. There is no universal sequence or single required publishing tool.
Chapter 1: Document-as-Code: Information We Can Work With · Chapter 7: From Sources to Results
4. Markdown is one source format
Open the chapter 4 playground after the session if useful. A file does not become reusable merely because it is Markdown. Structured records and specialized engineering models may be better represented in other formats. Prefer an accessible source that preserves the information.
5. Recording is not the same as approving
Keep this conceptual; it is not a Git walkthrough. A commit records a revision, not approval of every item. A review decision applies to a particular revision. If an AI agent changes several files, examine the relevant diffs and their consistency together.
Chapter 2: A Shared Workspace for Information · Chapter 3: History Is Useful Information
6. Give software explicit fields
These field names are project conventions, not requirements of Markdown or GitHub. Frontmatter is the opening metadata block; YAML is one way to write its fields. The chapter 5 practice schema accepts draft as a valid value. Passing that check does not approve the content. Ownership does not automatically grant approval authority.
7. Link information that must stay consistent
The diagram is illustrative, not an export of implemented records. A relationship identifies where to investigate; it does not prove that every linked item must change. Stable identifiers and clear relationship meanings are what make these references useful.
8. Make processing rules inspectable
Distinguish a valid record, accurate instructions, and an approved publication. Automation can detect a missing owner or an unsupported status, but it cannot establish every semantic claim. A build may succeed while the selected sources are still drafts.
Chapter 7: From Sources to Results · Chapter 10: Automating Information with GitHub Actions
9. Give AI relevant evidence, not just a prompt
Agents can inspect related files and instructions, but access alone does not ensure appropriate context. Select relevant versions, separate proposals from accepted requirements, and keep restricted information within its access boundaries. People remain responsible for checking results.
10. Try one complete information flow
Return to the tutorial homepage for the chapter groups and working labs. The goal is maintainable, traceable, reusable, processable information, not a change of editor. Start with one recurring information problem before building a broader platform.
Chapter 1: Document-as-Code: Information We Can Work With · Chapter 5: Structure Makes Information Actionable · Chapter 11: Behind the Lab: How We Built This Tutorial