Diagramming & Visualization

Tools and techniques for creating visual representations of technical concepts, system architectures, and workflows in API documentation. From straightforward flowcharts to complex infrastructure diagrams, this section covers software and approaches for making abstract concepts concrete and scannable to serve diverse reader needs.

C4 model

Definition: hierarchical approach to software architecture diagrams consisting of four levels - Context, Containers, Components, and Code; each level provides different abstraction for a different audience; created by software architect Simon Brown between 2006 and 2011

Purpose: provides consistent framework for API architecture documentation that serves both high-level stakeholders and implementation-focused developers; enables architects to communicate system design at the right level of detail for each audience without creating separate ad-hoc diagrams

the four levels

Number	Name	Abstraction	Shows	Audience
1	Context	Highest	How the system fits in the broader environment - users, external systems, integrations	Technical and non-technical; executives, product, architects, developers
2	Container	High	Applications, data stores, microservices, and how they communicate	Architects, developers, product; high-level technical audiences
3	Component	Low	Internal components within each container and their interactions	Architects and developers; low-level technical audiences
4	Code	Lowest	Implementation details - classes, modules, relationships; often auto-generated from code	Architects and developers; rarely used in practice as it can go into too much detail for most teams

Example: documenting a payments API using all four levels -

Context: payment system interacts with customers, merchants, and a third-party banking API
Container: API Gateway → Auth Service → Payment Service → PostgreSQL database
Component: Payment Service contains Invoice module, Fraud Detection module, and Ledger module
Code: class diagram showing how Invoice and Ledger classes relate, optional

Why this belongs in Tools & Techniques: describes a technique for structuring and communicating software architecture visually rather than a workflow methodology or organizational framework; while notation-independent and tool-independent, C4 is a practical technique applied at the diagram level - Structurizr and PlantUML are tools that implement it, but C4 itself belongs with the techniques that guide how docs teams create architecture diagrams

Related Terms: diagram, PlantUML, Structurizr, UML

Sources:

D2

Definition: modern DSL that turns text to diagrams; declarative diagramming language designed for software architecture diagrams with contemporary syntax and extensive layout options

Purpose: provides more expressive diagram-as-code capabilities than Mermaid for complex system architectures while maintaining text-based version control benefits

Example: define a microservices architecture in D2 syntax with containers, connections, and styling that renders as a professional architecture diagram -

api: API Gateway {
  style.fill: "#d4e8ff"
}
lambda: Lambda Functions
db: DynamoDB

api -> lambda: REST requests
lambda -> db: Query data

Related Terms: diagram, diagrams-as-code, docs-as-code, DSL, Ilograph, Mermaid, PlantUML, Structurizr, UML

Sources:

diagram

Definition: visual representation of a system, process, or concept that communicates technical information more efficiently than prose alone; in API documentation, diagrams typically represent architecture, data flows, sequences, or relationships between components

Purpose: helps docs teams select the appropriate visual type for the information they need to communicate; different diagram types serve different audiences and answer different questions, and choosing the wrong type forces readers to extract information the diagram wasn't designed to convey

common API docs diagrams

Type	What It Shows	Best For	Common Tools
Architecture	structural relationships between systems, services, and infrastructure	API system overviews, microservices topology, deployment context	D2, PlantUML, C4 model, Python Diagrams
ERD - Entity-Relationship	data models and relationships between entities	documenting API resource structures and database schemas	PlantUML, draw.io, Lucidchart
Flowchart	decision points and branching logic in a process	error handling flows, onboarding decision trees, conditional API behavior	Mermaid, draw.io, Excalidraw
Graph	nodes and edges showing connections or dependencies	API dependency maps, knowledge graphs, network topologies	Graphviz DOT, D2
Mind Map	hierarchical branching from a central concept	documentation planning, API feature overviews, taxonomy visualization	PlantUML, draw.io
Sequence	time-ordered interactions between systems or components	documenting API request-response flows, authentication steps, webhook event chains	Mermaid, PlantUML

Example: documenting a payment API requires multiple diagram types to serve different reader needs -

Architecture Diagram: shows how the payment service, fraud detection service, and database relate within the broader system
ERD: shows the relationships between Payment, Transaction, Refund, and Webhook resources
Flowchart: shows decision logic for handling payment failures, retries, and fallback behavior
Sequence Diagram: shows the step-by-step flow of a payment transaction from client request through auth, processing, and webhook callback

Sources:

draw.io

Definition: also known as diagrams.net - free, open source diagramming tool for creating flowcharts, network diagrams, UML diagrams, and technical architecture visualizations

Purpose: enables tech writers to create professional diagrams without licensing costs; supports export to multiple formats including PNG, SVG, and PDF for embedding in documentation

Example: create an AWS architecture diagram showing API Gateway → Lambda → DynamoDB flow with proper AWS service icons, then export as SVG for docs embedding

Related Terms: diagram, Excalidraw, Ilograph, Lucidchart, SVG, UML

Sources:

DSL

Definition: acronym for domain-specific language; a programming or specification language designed for a particular domain, problem space, or tool rather than general-purpose software development

Purpose: helps tech writers understand and document the specialized syntax and conventions that appear across API documentation tooling; particularly relevant in diagramming and visualization contexts, where many tools - D2, Mermaid, PlantUML - use their own DSL to define diagrams as text rather than through graphical interfaces

Why this belongs in Diagramming & Visualization: DSL appears repeatedly as a characteristic of diagramming tools that API docs teams use; understanding that a tool has its own DSL shapes how writers document it, explaining not just what the tool produces but how users write in it, including its syntax rules, constraints, and vocabulary; while DSLs exist across many tool categories, diagramming tools represent the most consistent and concentrated use of the term in API docs contexts

Example: common tools, including diagramming tools, used in API docs that implement their own DSL -

Tool	DSL Style	Example Syntax
Cucumber / Gherkin	Gherkin syntax	`Given / When / Then` scenario structure for docs-as-tests workflows
D2	Declarative text syntax	`server -> database: query` defines a connection with a label
GraphQL	GraphQL schema definition language	type definitions, queries, mutations, and resolver patterns
Graphviz DOT	Graph description language	`digraph { a -> b }` defines a directed graph
Markdown	Markdown syntax	formatting conventions, extensions, and rendering differences across platforms
Mermaid	Markdown-inspired text syntax	`graph TD; A-->B` defines a top-down flowchart
OpenAPI Specification	YAML/JSON schema syntax	structure, rules, and field conventions of the spec format
PlantUML	Keyword-based text syntax	`@startuml / @enduml` wraps sequence diagram definitions

Sources:

Excalidraw

Definition: open source sketching tool that creates hand-drawn style diagrams with a minimalist interface and collaborative features

Purpose: provides quick, low-fidelity diagramming for documentation where informal visual style aids comprehension without the overhead of polished graphics

Example: sketch a request-response flow between client and API server using hand-drawn boxes and arrows that render instantly without design decisions

Related Terms: diagram, draw.io, Lucidchart, request-response, SVG

Sources:

Ilograph

Definition: interactive diagramming tool for software architecture that creates layered, explorable views of systems; renders navigable visualizations from text and/or YAML files; available online, on-prem, and in Confluence Cloud

Purpose: enables docs teams to create architecture diagrams that users can explore interactively, drilling down into different levels of system detail without creating separate diagrams for each view

Example: define a microservices architecture once in Ilograph syntax, then users can click to expand individual services to see their internal components, database connections, and API endpoints

Related Terms: D2, diagram, diagrams-as-code, draw.io, Mermaid, Structurizr, YAML

Sources:

Lucidchart

Definition: web-based diagramming tool with real-time collaboration features, extensive shape libraries, and integrations with documentation platforms

Purpose: enables teams to collaboratively create and maintain technical diagrams with professional templates for system architecture, API flows, and network topologies

Example: multiple technical writers simultaneously update a microservices architecture diagram while integrating it with Confluence documentation

Related Terms: diagram, draw.io, Excalidraw

Sources:

Mermaid

Definition: JavaScript-based diagramming tool that renders text-based diagram definitions into flowcharts, sequence diagrams, and other visualizations directly in Markdown files; particularly common in docs workflows

Purpose: enables streamlined diagrams in API documentation through text markup that renders visually in docs platforms supporting Mermaid syntax

Example: Mermaid sequence diagram showing API request flow without requiring external image files -

Related Terms: D2, diagram, diagrams-as-code, docs-as-code, Ilograph, Markdown, MDX, PlantUML, UML

Sources:

PlantUML

Definition: DSL and text-based diagramming tool that generates architecture, sequence, and UML diagrams from plain text markup; has support for other software development related formats such as Archimate, Block diagram, BPMN - Business Process Model and Notation -, C4 model, computer network diagram, ERD - entity-relationship diagram -, Gantt chart, mind map, and WBD - work breakdown structure - as well as visualisation of JSON and YAML files

Purpose: enables version-controlled diagrams in API documentation through text-based source files that render visually in docs platforms; supports multiple input languages and output formats making it adaptable to diverse docs workflows and accessibility needs

Language Support: besides its own DSL, PlantUML understands AsciiMath, Creole, DOT, and LaTeX - making it interoperable with other text-based docs and diagramming ecosystems

Output Formats: renders diagrams as PNG, SVG, LaTeX, and ASCII art - notably, ASCII art output makes PlantUML diagrams consumable in plain-text environments like terminals, email, and code comments

Accessibility: PlantUML's text-based input and ASCII art output enables blind users to both design and read UML diagrams - making it one of the few diagramming tools with meaningful accessibility applications beyond visual rendering

Example: write text markup describing an API authentication sequence, then render it automatically in documentation as a visual sequence diagram

@startuml
Client -> API: POST /auth/login
API -> Database: Validate credentials
Database --> API: User token
API --> Client: 200 OK {token}
@enduml

Related Terms: C4 model, D2, diagram, diagrams-as-code, DSL, JSON, Mermaid, Python Diagrams, Structurizr, UML, YAML

Sources:

Python Diagrams

Definition: Python library that generates infrastructure architecture diagrams using code; includes pre-built icons for AWS, Azure, GCP, Kubernetes, and other cloud services

Purpose: enables version-controlled, reproducible infrastructure diagrams in API documentation through code rather than manual drawing tools

Example: write Python code that generates an AWS architecture diagram with proper service icons, then commit both the code and output image to version control -

from diagrams import Diagram
from diagrams.aws.compute import Lambda
from diagrams.aws.network import APIGateway
from diagrams.aws.database import Dynamodb

with Diagram("API Architecture"):
    APIGateway("API") >> Lambda("Function") >> Dynamodb("Database")

Related Terms: commit, diagram, diagrams-as-code, docs-as-code, PlantUML, version control

Sources:

Structurizr

Definition: toolset for creating software architecture diagrams based on the C4 model - Context, Containers, Components, Code; uses a domain-specific language to define architecture as code

Purpose: enables consistent, hierarchical architecture documentation that maintains relationships between different abstraction levels in API docs

Example: define system architecture once in Structurizr DSL, then automatically generate context diagrams for executives, container diagrams for architects, and component diagrams for developers

Related Terms: C4 model, D2, diagram, DSL, Ilograph, PlantUML, UML

Source:

SVG

Definition: acronym for Scalable Vector Graphics; an XML-based markup language for describing two-dimensional based vector graphics; essentially to graphics what HTML is to text; text-based image format and open Web standard that supports interactivity and animation

Purpose: enables high-quality diagrams in API documentation that remain crisp at any zoom level and can include interactive elements like clickable regions or tooltips

Example: export architecture diagrams as SVG files that scale perfectly across desktop and mobile documentation views without pixelation

Related Terms: diagram, draw-io, Excalidraw, XML

Sources:

UML

Definition: acronym for Unified Modeling Language; standardized visual modeling language for describing software systems through a family of diagram types covering structure, behavior, and interaction

Purpose: provides a common visual vocabulary for documenting software architecture and behavior in API documentation; understanding UML helps writers recognize and document diagram types produced by tools like PlantUML, draw.io, and Lucidchart, and communicate accurately with engineers who use UML notation in architecture discussions

UML diagrams in API docs

Category	Diagram Type	What It Shows
Structural	Class Diagram	object types, properties, and relationships in an API's data model
Structural	Component Diagram	how system components and APIs connect and depend on each other
Behavioral	Activity Diagram	workflow logic, decision points, and branching in API processes
Behavioral	Sequence Diagram	time-ordered message exchanges between components in an API flow
Behavioral	State machine Diagram	how a resource changes state -`pending` → `processing` → `complete`
Interaction	Use Case Diagram	how different actors, users, systems, interact with an API

Example: a tech writer documenting an order management API uses UML sequence diagrams to show the message exchange between client, API gateway, and fulfillment service, then UML state machine diagrams to show how an order moves through pending, confirmed, shipped, and delivered states

Related Terms: C4 model, diagram, D2, diagrams-as-code, draw.io, DSL, Mermaid, PlantUML, Structurizr

Sources:

C4 model​

the four levels​

D2​

diagram​

common API docs diagrams​

draw.io​

DSL​

Excalidraw​

Ilograph​

Lucidchart​

Mermaid​

PlantUML​

Python Diagrams​

Structurizr​

SVG​

UML​

UML diagrams in API docs​

C4 model

the four levels

D2

diagram

common API docs diagrams

draw.io

DSL

Excalidraw

Ilograph

Lucidchart

Mermaid

PlantUML

Python Diagrams

Structurizr

SVG

UML

UML diagrams in API docs