Skip to main content

Diagrams and Screenshots That Carry Weight

What This Concept Is​

A load-bearing diagram replaces paragraphs instead of decorating them. A decorative diagram sits next to text that already says the same thing -- it costs the reader attention without paying anything back. The distinction is binary: either your diagram answers a specific question the prose does not, or it does not belong.

Same rule for screenshots: a good screenshot answers a question the reader is already asking ("does this thing actually run?", "what does the failure mode look like?"). A bad screenshot is a hero image of a dashboard nobody needed to see.

A useful test: imagine removing the diagram and replacing it with a one-sentence caption. If the caption gives you the same information, delete the diagram. If the caption would need to be a paragraph, the diagram is earning its space.

The highest-leverage diagrams in a capstone case study carry semantics: delivery guarantees on edges, consistency regimes on stores, trust boundaries on network calls, failure domains on partitions. Boxes-and-arrows without semantics are the engineering equivalent of clip art.

Why It Matters Here (In the Capstone)​

Reviewers scan visuals before they read. The first diagram in a case study is the single highest-leverage paragraph-sized object in the document -- because it is not a paragraph. You can show data flow, failure modes, or deploy topology in a way prose cannot.

The inverse is also true: if the first diagram is low-signal (a generic "system diagram" with eight boxes and no failure semantics), the reader concludes the rest of the document is the same. Whether that is fair or not, it happens. The first diagram sets the document's credibility ceiling before the first paragraph is read.

In a capstone specifically, diagrams are also the single most reusable artifact you produce. The same three load-bearing diagrams will appear in your case study, your portfolio README, your blog post, and your live interview whiteboard. Investing in them once is not decoration; it is leverage.

Concrete Example: Two Diagrams for the Same Service​

Weak:

This diagram has three boxes and adds nothing. The reader learned nothing they could not have guessed.

Strong:

The strong version shows: three feeds with different delivery semantics, the exact place idempotency is enforced, the key used, and the read/write split. A reviewer can now ask a specific question like "what happens if Redis loses the dedupe window?" That question is the whole point -- the diagram invited it.

Concrete Example: The Three-Diagram Budget​

For a capstone case study, three diagrams usually carry the whole document. A typical allocation:

DiagramQuestion it answersRequired labels
ArchitectureWhat are the major pieces and how do they talk?Protocols, delivery semantics on each edge
Data flow (or sequence)What is the non-obvious path through the system?Ordering, idempotency points, retries
Failure modeWhat breaks when X dies, and what does the system do?Timeouts, fallbacks, what the user sees

A fourth diagram (e.g., deploy topology) is acceptable only if it answers a question the first three do not. Most cases it does not.

Common Confusion / Misconceptions​

Diagrams as summary art. "I need a system diagram" is almost always the wrong starting question. The right question is: what is the reader about to misunderstand? A diagram exists to prevent that specific misunderstanding.

Too many diagrams. Three strong diagrams (architecture, data flow, failure mode) beat ten weak ones. A diagram-heavy case study often hides a prose-weak one.

Cropping fails. A tiny centered screenshot of a dashboard proves nothing. Either show enough to read the axis labels or do not include it. If the screenshot's text is not legible in the rendered document, it is not a screenshot -- it is a rectangle of noise.

Beautiful > correct. A diagram that looks polished but lies about delivery semantics ("exactly-once" labeled on a best-effort path) is worse than an ugly honest one. Correctness dominates aesthetics in technical diagrams; senior reviewers check.

How To Use It (In Your Capstone)​

For each potential visual, ask:

  1. What reader question does this answer?
  2. Can prose answer it in one sentence? If yes, skip the visual.
  3. Does the visual name specific quantities, semantics, or failure boundaries?
  4. Is the visual legible at the size it will actually be rendered?
  5. Does each edge carry a label (protocol, delivery guarantee, consistency)? If not, the diagram is a sketch, not an artifact.
  6. Does the diagram map one-to-one back to an ADR or design note? If not, either the diagram or the ADR is missing.
  7. Would the diagram survive a hostile reading by someone who knows your domain better than you do?

Concrete heuristics:

  • one architecture diagram (boxes + edges with labels, not unlabeled arrows)
  • one data flow or sequence diagram for the non-obvious path
  • one failure-mode or degradation diagram if the system has one
  • zero generic "tech stack" diagrams

Check Yourself​

  1. For each diagram in your draft, what question is it answering?
  2. Are arrow labels present where delivery semantics, retry, or consistency guarantees differ?
  3. What is the total number of visuals? If it is more than four, which two are cut candidates?
  4. Does your first diagram invite a specific follow-up question? If not, it is decoration.
  5. Is each diagram legible at the width it will render on the portfolio site?
  6. Does each diagram trace back to a specific ADR or design note?

Mini Drill or Application (Capstone-scoped)​

Three drills:

  1. Edge-label pass. Take your current best architecture diagram. Add one label per edge describing the guarantee being carried (e.g., exactly-once, at-least-once, sync RPC, async event). Does the diagram now tell a story it was not telling before? If yes, keep. If no, replace.
  2. Failure diagram drill. Draw a third diagram showing what happens when your single most critical dependency fails. Label the user-visible effect, the timeout, the fallback, and the recovery path. If you cannot, you do not yet understand your own failure mode.
  3. Diagram-to-ADR audit. For every diagram in your draft, find the ADR that justifies its shape. Any orphan diagrams are either un-decided or un-documented; either write the ADR or remove the diagram.
  4. Hostile-reading drill. Ask one peer to attack the first diagram with the single sharpest question they can think of. If the question lands a gap (e.g., "what happens if Redis is cold?"), the diagram earned its space by exposing the gap. If the peer has no question, the diagram is decoration.

Commit all three outputs under library/raw/case-study/diagrams/ and link them from the case study.

Transfer / How This Synthesizes Prior Semesters​

A load-bearing diagram is just the visual form of every semantic distinction you learned to name through the degree:

If an edge in your diagram cannot be labeled with vocabulary from at least one of those modules, the line is a guess drawn in a meeting, not an engineering artifact.

See also (integrative)​

Source Backbone​

Portfolio assessment packages evidence from the whole curriculum. These books provide the technical and professional backbone for the narrative.