Images, Diagrams, and Visual Sources

A visual is part of the information we maintain, not just decoration added when publishing. A diagram can explain how a requirement connects to work and verification. A chart can reveal a change in the project. A screenshot can show a detail that prose would struggle to describe.

Document-as-code does not require replacing visual tools with text. It asks us to identify the editable source, record what the visual means, and keep it aligned with related information. The source might be Mermaid, an SVG drawing, a dataset, or a model in a specialist application.

We will extend chapter 7’s onboarding example into a generated diagram, then consider visual delivery and maintenance. The main exercise uses the existing Python environment. Rendering and the optional Napkin comparison use separate tools; generating source text and checking the visible result are separate tasks.

Choose the Visual for the Question

Start with what a reader needs to understand:

Mermaid and SVG serve different roles. Mermaid describes diagrams; SVG is a vector image format that can carry a rendered diagram or a directly authored drawing. An exported image and its editable source may therefore use different formats.

Describe Relationships with Mermaid

Mermaid turns text descriptions into diagrams. You name items and connections, while a renderer arranges and draws them. Its source can be reviewed alongside prose in a diff. The Mermaid introduction describes this approach.

This authored diagram connects chapter 7’s records to the draft procedure. The procedure connection is explanatory judgment, not a link stored in record metadata.

flowchart LR
    procedure["PROC-001: draft procedure"]
    task["TASK-003: implementation work"]
    requirement["REQ-014: reference-number requirement"]
    test["TEST-008: planned test"]
    task -->|implements: intended work| requirement
    requirement -->|verified_by: intended check| test
    procedure -. conceptual connection only .-> requirement

Record links express intended implementation and verification, not completed work.

The solid arrows show relationships stored in the records and checked by the processor. The dashed arrow connects the procedure to the scenario for the reader; it is not a stored relationship. We chose these arrow styles to distinguish the two meanings.

This diagram is written in Mermaid but is not generated from the records. Changing a record therefore does not update the diagram automatically. Include related diagrams and explanations in the review of a change: regenerate outputs built from data, and edit maintained illustrations where needed. Keep a historical example unchanged only when it is clearly labelled as such.

For a diagram answering only “what relationships are recorded?”, we can generate the source instead. This avoids maintaining those same connections twice. It does not remove the need to review selection rules or the resulting layout.

Display Mermaid in Markdown

To display a Mermaid diagram in GitHub’s Preview view, put its instructions inside a fenced block labelled mermaid. This teaching example uses four backticks around the outer block so its three-backtick fences stay visible:

```mermaid
flowchart LR
    request["Access request"] --> review["Team review"]
```

Here, flowchart LR requests a left-to-right layout. request and review identify the nodes, the bracketed text supplies their labels, and --> connects them with an arrow. The label on a code fence matters: a markdown block shows these instructions as text; a supported mermaid block renders the diagram.

Editable .mmd files hold Mermaid source on its own. Linking to one lets readers inspect the instructions; embedding a Mermaid block lets a compatible renderer display them in the chapter. Keep the embedded instructions aligned with their maintained source.

Different renderers may support different Mermaid versions or features. Check the result on GitHub and in each publication you produce. GitHub’s diagram guide explains its support and version checks.

Let Records Supply the Connections

The diagram generator reuses chapter 7’s validation. It includes every validated record, including unconnected records, and draws only explicit relationships defined in the schema. It does not infer links from prose or include the separate procedure file.

With the supplied starting records, it produces this Mermaid source and view:

flowchart LR
    n0["REQ-014: requirement"]
    n1["REQ-015: requirement"]
    n2["TASK-003: task"]
    n3["TEST-008: test"]
    n0 -->|verified_by| n3
    n2 -->|implements| n0

The starting dataset contains four records and two explicit relationships. This fixed teaching example is not a live view of your exercise files.

REQ-015 has no arrow because no relationship is recorded for it. That does not prove it is unrelated to the service. Likewise, verified_by identifies an intended test, not a passing result. The diagram omits status and owner; use chapter 7’s dashboard for those questions.

flowchart LR requests a left-to-right arrangement. Names such as n0 are generated drawing identifiers, not record IDs; the labels retain the record IDs. Text between vertical bars names an arrow’s relationship. Mermaid’s flowchart reference explains the notation.

Separate Generation, Rendering, and Refresh

From the repository root, with the Python environment from the measurement reference active, run:

python scripts/build_record_diagram.py

The result under build/record-diagram/ contains relationships.mmd, a Markdown wrapper named relationships.md, and manifest.json. The manifest hashes the schema, records, generator, and shared validator. Preserve inputs as well as hashes to reproduce a result.

The script generates text, not SVG or PNG. Open the wrapper in a Mermaid-capable preview. A plain text editor shows the instructions instead. GitHub does not run this generator merely because you open a file, and generated files under build/ are ignored by Git.

For local image export, follow the official Mermaid CLI instructions. Once its mmdc command is installed, request an SVG export with:

mmdc -i build/record-diagram/relationships.mmd -o build/record-diagram/relationships.svg

Record the renderer version and inspect the export. The renderer is not included in this project’s Python dependencies, and this draft does not claim verified rendering across GitHub, PDF, and PowerPoint. The Mermaid section above explains preview compatibility; the automation and quality guide covers repeatable build checks.

SVG, Raster Images, and Native Sources

SVG describes vector shapes and text rather than only a fixed grid of pixels. It is useful for scalable diagrams and illustrations, and can be produced by code or edited with visual tools. MDN’s SVG overview explains the XML-based format.

An SVG export does not necessarily preserve a diagram’s editable meaning. Moving an exported arrow in a graphics editor will not update the Mermaid source or record relationship. Decide whether the edit belongs in the original source, a deliberate presentation variant, or a separately maintained drawing.

Raster images store pixels. Use them for photographs and screenshots, or when a destination requires a bitmap. Choose dimensions for the intended display or print size. Check that compression does not obscure labels or details the reader needs.

For a SysML model, animation, or complex illustration, preserve the native source and its tool/version information. A screenshot or video export may communicate the result without preserving the model’s constraints or editing capabilities. Do not force a rich model into Markdown merely to call it document-as-code.

Charts Need Data, Not Invented Shapes

The Project Control Center’s growth charts are generated from measured history. Keep the data, selection rules, units, and revision identity alongside a chart. A plausible curve is not a substitute for observations.

An AI agent can help write plotting code or explain a chart. Review the input selection and calculations as well as the image. Do not add observations to make a sparse history look convincing. When data changes, regeneration and review of captions and conclusions belong to the same update.

Napkin and AI-Assisted Visual Exploration

Napkin starts from text, generates candidate visuals, and lets you edit a chosen result. Its site lists image and document export options, with some formats dependent on the plan. Check account entitlements before relying on a particular export. Napkin’s product overview describes the workflow.

Use it to explore a teaching illustration or presentation composition. Keep the supplied text and editable project, not just the final export. Review whether the visual invents a sequence, hierarchy, quantity, or causal relationship that the source does not support.

For an optional comparison, use this fictional brief in Napkin or another permitted visual tool:

Show three related items: TASK-003 is intended to implement REQ-014.
TEST-008 is intended to verify REQ-014. Do not imply completed work or
a passed test. REQ-015 has no recorded relationship in this dataset.
Keep the record IDs visible. Do not add a timeline or quantities.

Compare the result with Mermaid: which preserves the meaning more clearly, and which is easier to update? This account-dependent exercise is optional. No Napkin project or integration has been created for the tutorial.

Make Visual Updates Part of the Change

Use generators for connections and counts that follow explicit rules. Use people and agents for authored explanations that require judgment. Both belong in a coordinated update process.

For this example, check the records, generated diagram, the authored diagram above and explanations, embedded teaching examples, and affected captions. Fixed snapshots may deliberately remain unchanged, but must remain labelled rather than becoming stale current-state claims.

Ask an agent to report updated items, checked-but-unchanged items, and unverified items. Supply dependencies and generation commands through project instructions or skills. A harness can run checks and record results; this repository does not yet discover every affected visual automatically.

Make Visuals Understandable and Traceable

Provide a caption explaining the point, alternative text describing essential information, and a longer explanation or data table when needed. Do not encode important distinctions through color alone. W3C’s complex-image guidance explains descriptions for charts and diagrams.

For an image in Markdown, put the alternative description between square brackets after !, followed by the image path in parentheses:

![Baseline chart with one revision, 10 chapter outlines, 829 prose words, and zero completed capabilities.](../assets/figures/growth-baseline.png)

Alternative text explains the image when a reader cannot see it; a visible caption connects it to the discussion. For a complex chart, include its values in a table or explain the main findings in the surrounding text. Check that descriptions, labels, and captions remain useful in the published output, not only in the source.

Check labels, arrow direction, contrast, clipping, and reading order at the intended size. A desktop diagram may need another arrangement in print or on a slide. For animations, provide an equivalent static explanation or transcript.

Keep source paths, input revisions or hashes, export methods, and tool versions available. Record origin, creator, license, and attribution requirements for external assets. AI generation is not blanket permission to publish. Do not supply confidential material to external tools without authorization.

Try It: Change a Relationship

Use your own exercise copy and the Python environment from the measurement reference. No external AI service is required.

1. Run the generator. Inspect its Mermaid text and manifest, then preview it if a renderer is available. Use your actual records if earlier exercises added items.
2. In TASK-003, temporarily change implements: [REQ-014] to implements: [REQ-015]. This is a fictional maintenance experiment, not a product decision. Predict which arrow will move.
3. Regenerate. Verify that the task now points to REQ-015, while REQ-014 still points to TEST-008. Check that the manifest digest changed.
4. Compare the result with the authored diagram above. Note which explanations would need review for an intended change. Do not rewrite fixed teaching examples for this temporary experiment.
5. If a renderer is available, export SVG and inspect it at a book-column or slide size. Compare its content with the source, not just its appearance. Optionally compare with Napkin using the same relationships.
6. Restore the task’s original relationship and regenerate. The original diagram source and input digest should return when no other inputs have changed.

Expected result: a record change updates the generated arrow without manually editing Mermaid. The authored diagram does not change by itself; it is an explicit review dependency. Mark rendering unverified if no compatible renderer is available.

If generation fails: check the field and target ID against the schema. Invalid references stop processing before writing outputs; older files may remain. If text is generated but no diagram appears, check Mermaid support in the preview separately.

Keep: comparison notes, input references, and any reviewed visual variant. Restore the temporary experiment; generated files remain under ignored build/. For your information item from chapter 1, identify one useful visual, its maintained source, and the checks needed when it changes.

Next, Git, Review, and Collaboration develops review of coordinated changes and the scope of approval.