Why Document-as-Code? From Document Production to Information Value
Speaker notes · Suggested session length: 15 minutes
Launch the presentation · Tutorial home
1. We need usable information
Begin with a practical question: what information decision is difficult today? This session addresses value and adoption, rather than teaching syntax or configuring tools. The examples are illustrative; they do not establish measured savings.
Chapter 1: Document-as-Code: Information We Can Work With · Chapter 11: Behind the Lab: How We Built This Tutorial
2. One change can create several updates
Invite an example of duplicated information from the audience. Independent copies may be appropriate when audiences need different content, but shared facts and instructions need an intentional maintenance strategy. A new repository alone does not resolve that problem.
3. Reuse the maintained source
The intended benefit is fewer independently maintained copies, not identical output everywhere. A training excerpt can omit details that remain in the full procedure. Changes reach an output when its processing and publication rules run.
Chapter 1: Document-as-Code: Information We Can Work With · Chapter 10: Automating Information with GitHub Actions
4. Make the history useful to the team
History is useful for explanation and follow-up, not ranking contributors. Commit counts and word counts are activity measures, not quality scores. Identity and review records need to be interpreted within the team's agreed approval process.
6. Automate work that repeats
Do not promise a percentage improvement without evidence. These are candidates for reducing repeated work. Scripts, checks, and publishing rules require ownership and maintenance; compare that effort with the actual recurring task.
Chapter 7: From Sources to Results · Chapter 10: Automating Information with GitHub Actions
7. Find where a change may matter
Use a security policy as the example, not employee task readiness. A reference does not automatically mean a procedure must change. It makes the candidate set visible, so a responsible person can assess the impact.
8. AI becomes more useful with reliable context
The opportunity is more than fluent writing. An agent may inspect a connected set of sources, constraints, and processing code. That also increases the review surface. Protect access boundaries and review generated changes across all affected files.
9. Autonomy brings maintenance responsibility
Not every conversation or temporary note needs this treatment. A hybrid approach can keep authoritative information in existing systems and import only what is needed. Teams need practical permission to improve their workflow, with boundaries for security and platform responsibilities.
Chapter 11: Behind the Lab: How We Built This Tutorial · Chapter 2: A Shared Workspace for Information
10. Pilot a real information problem
Choose measures suited to the problem rather than tracking more activity for its own sake. Review results with the people maintaining and consuming the information. Continue only where the benefit justifies the effort. The tutorial's labs provide examples, not a universal adoption score.
Chapter 11: Behind the Lab: How We Built This Tutorial · Chapter 3: History Is Useful Information