PlantUML
PlantUML turns text descriptions into diagrams. Its value in documentation comes from keeping the explanation reviewable beside the code or design it describes. The diagram still needs a clear scope, correct relationships, understandable labels, and a rendering process the team can reproduce.
Choose the reader’s question before the diagram type. A sequence diagram can explain request order and failure paths; a component or deployment view can explain structure and responsibility. Trying to answer every question in one drawing usually produces a very organized wall of arrows.
TL;DR
- Choose a structure or behavior view from the reader’s task.
- Keep diagram source close to its owning documentation or system.
- Pin renderer and relevant layout/font inputs for repeatable builds.
- Review rendered output as well as source changes.
- Treat includes and remote rendering as data-access boundaries.
Quick Example
This fictional sequence diagram separates job acceptance from completion and shows a status-polling budget with a failed or unresolved branch. Save it as report-flow.puml in a suitable PlantUML documentation project.
The source received manual review; it was not rendered because a Java/PlantUML runtime was not available. No syntax-engine acceptance, visual layout, accessible alternative, or deterministic output result is claimed. A real diagram should specify the actual job contract and meaningful polling limits.
Core Concepts
Source and output
PlantUML’s command-line interface processes supported source files and emits diagrams. Build scripts should use the documented interface for their pinned renderer version, rather than assuming every newer or beta option is available. Command-line reference
Model selection
Use separate views for different concerns. A behavior diagram should make an important interaction and its alternatives clear; a structure diagram should explain relationships at a consistent level of abstraction. Neither is automatically a complete specification.
Renderer access
PlantUML documents security profiles that constrain file and URL access. In particular, SANDBOX denies both, while ALLOWLIST uses explicit permitted resources. Select the actual build policy deliberately. Security profiles
Make each view earn its place
Keep names aligned with the surrounding documentation. If a diagram calls something Worker and the implementation calls it Export Processor, explain the relationship or choose one consistent domain term. Abbreviations should reduce clutter without creating a second vocabulary.
Show the boundary the reader needs to reason about. For the example, accepted and completed are different messages because the distinction affects recovery. Omitting the unresolved branch would make the happy path look simpler while removing useful operating information.
State the diagram’s scope in nearby prose. Identify omitted components and whether the picture describes current behavior or a proposal. A design diagram can remain technically valid while becoming misleading after the service responsibilities change.
Control build inputs and inspect the artifact
Record the PlantUML version, Java runtime, relevant layout engine, fonts, themes, and include content used by the build. Which inputs matter depends on the diagram types and configuration. Pin or otherwise control them before describing the process as reproducible.
Avoid remote mutable includes when a stable local dependency is appropriate. If an approved external resource is required, record its version or content identity and the allowed access path. A network response changing during a documentation build should not silently rewrite the design vocabulary.
Run the chosen renderer in a clean documentation build and fail on the errors your pinned version exposes. Exercise a deliberately invalid diagram to confirm the build actually rejects it. Do not replace a renderer’s syntax check with a homemade count of start/end markers.
Compare rendered output after dependency updates. Check clipping, tiny labels, layout shifts, branch readability, and the relationship between the diagram and accompanying text. Byte-for-byte differences and meaningful visual differences are separate questions.
Provide a usable textual explanation or alternative for the important meaning. A diagram rendered as an image can be difficult to navigate or understand without context, particularly when labels or color carry the only explanation.
Keep rendering inside the intended trust boundary
Treat diagram source as input to a renderer with dependencies and access rights. Includes, links, and generated metadata can disclose more than the visible drawing suggests. Use the documented security profile and an appropriately bounded build environment.
Do not send internal system diagrams to a public renderer merely because it is convenient. Confirm the approved destination and data handling before using an external service. Local rendering can keep source within the chosen environment, but still needs controlled dependencies and resource limits.
For contributions from untrusted sources, review the execution environment, network access, and file access independently of whether the text appears to be a harmless diagram. Do not weaken protective settings just to make an include work.
Start adoption with a small diagram, a pinned build, one deliberate failure case, and a review of the rendered artifact. Add more notation only when it makes the reader’s question easier to answer.
Best Practices
Review meaning before layout
Confirm the participants, directions, states, and alternatives match the actual system. A beautifully rendered incorrect flow is still incorrect.
Keep dependencies visible
Track renderer, includes, themes, fonts, and any layout engine. Review output when those inputs change.
Test the failure path
Confirm invalid source fails the documentation build, and verify that inaccessible dependencies produce a clear diagnostic.
Common Mistakes
Bad: Text source makes output automatically deterministic.
Correct: Control the relevant runtime, renderer, layout, fonts, and includes, then compare repeated builds.
Bad: One diagram should describe the entire system.
Correct: Choose focused views tied to distinct reader questions.
Bad: A public renderer is just a display tool.
Correct: Review source transmission and rendering access before sending internal material.
FAQ
Should diagram images be committed?
Follow the repository’s documentation workflow. If generated artifacts are committed, keep their source and reproducible build relationship clear.
Does a valid source guarantee a useful diagram?
No. Inspect meaning, layout, readability, and a suitable text explanation.
Was this example rendered?
No. It is a manually reviewed source example; runtime syntax and output checks remain pending.
Related Topics
- Technical Diagrams — Choosing and maintaining useful technical views.
- Docs-as-Code — Documentation builds and repository review.
- Mermaid — Another text-diagram workflow and notation.