Skip to main content

​
Depth Assessment

Before designing any diagram, determine what level of detail it needs. This is the first decision you make — before research, before planning, before anything else. The depth determines everything that follows.

​
The Two Categories

​
Simple/Conceptual Diagrams

Use abstract shapes when:
  • Explaining a mental model or philosophy
  • The audience doesn’t need technical specifics
  • The concept IS the abstraction (e.g., “separation of concerns”)
  • You want a quick overview or summary
  • The audience already knows the details
Time to explain: ~30 seconds
What viewers learn: The structure

​
Comprehensive/Technical Diagrams

Use concrete examples when:
  • Diagramming a real system, protocol, or architecture
  • The diagram will be used to teach or explain (e.g., YouTube video, documentation)
  • The audience needs to understand what things actually look like
  • You’re showing how multiple technologies integrate
  • You want the diagram itself to teach
Time to explain: ~2-3 minutes
What viewers learn: The structure AND the details
For technical diagrams, you MUST include evidence artifacts. See the Evidence Artifacts page.

​
Decision Framework

Use this comparison table to decide which type you need:
AspectSimple DiagramComprehensive Diagram
LabelsGeneric: “Input” → “Process” → “Output”Specific: shows what the input/output actually looks like
ComponentsNamed boxes: “API”, “Database”, “Client”Named boxes + examples of actual requests/responses
Events”Events” or “Messages” labelTimeline with real event/message names from the spec
UI Elements”UI” or “Dashboard” rectangleMockup showing actual UI elements and content
Explanation time~30 seconds~2-3 minutes of teaching content
Learning outcomeViewer learns the structureViewer learns the structure AND the details
Research requiredMinimalExtensive — look up actual specs

​
Examples

​
Simple Diagram Example

Showing the concept of a feedback loop: 
Input → Process → Output
  ↑                 ↓
  └─── Feedback ────┘
No specific technologies, no real data formats — just the abstract concept.

​
Comprehensive Diagram Example

Showing a real streaming protocol integration: 
CopilotKit Runtime
├─ AG-UI streams:
│  • RUN_STARTED
│  • STATE_DELTA  
│  • A2UI_UPDATE
│
└─> Frontend renders via:
    createA2UIMessageRenderer({
      component: CustomUI
    })
Real event names, actual API methods, concrete examples.

​
When Comprehensive Is Required

If you’re creating diagrams for:
  • Documentation sites → Comprehensive
  • Educational content → Comprehensive
  • Architecture reviews → Comprehensive
  • Integration guides → Comprehensive
  • System design tutorials → Comprehensive
These contexts demand accuracy and teaching value.

​
The Research Mandate

For comprehensive/technical diagrams, research the actual specifications before designing. If you’re diagramming a protocol, API, or framework:
  1. Look up the actual JSON/data formats
  2. Find the real event names, method names, or API endpoints
  3. Understand how the pieces actually connect
  4. Use real terminology, not generic placeholders

​
Bad vs Good

Bad

“Protocol” → “Frontend”Generic, teaches nothing.

Good

“AG-UI streams events (RUN_STARTED, STATE_DELTA, A2UI_UPDATE)” → “CopilotKit renders via createA2UIMessageRenderer()”Specific, educational, accurate.
Research makes diagrams accurate AND educational.When viewers see real event names and actual API calls, they learn what things actually look like — not just what they’re conceptually called.

​
Common Mistake

The most common mistake is creating a simple diagram when a comprehensive one is needed. Symptom: Someone looks at your diagram and asks “But what does the data actually look like?” or “What’s the real API method name?” Fix: Go back and add evidence artifacts. Show concrete examples. Do the research.

​
Next Steps

Once you’ve determined your diagram needs to be comprehensive:
  1. Read Evidence Artifacts to understand what to include
  2. Read Multi-Zoom Architecture to structure your diagram at multiple levels
  3. Start with research before you design anything

Build docs developers (and LLMs) love

Get started for freeTalk to us