Generated using AI. Be aware that everything might not be accurate.


Chapter 6: Diagrams, Visuals, and Formatting

A wall of text is hard to parse. A wall of code is harder. Visual elements — diagrams, tables, callout boxes, and thoughtful formatting — break up density and communicate certain ideas far better than prose ever could. This chapter covers when and how to use visuals effectively in a technical book.

When a Diagram Is Worth a Thousand Words

Not everything needs a diagram. But some concepts are almost impossible to teach without one:

  • Architecture and system design: How components connect and communicate.
  • Data flow: How a request moves through a system.
  • State machines: How an entity transitions between states.
  • Hierarchies and relationships: Inheritance trees, database schemas, network topologies.
  • Timelines and sequences: What happens in what order, especially with concurrent processes.

If you find yourself writing “A sends a message to B, which then forwards it to C, which stores it in D and notifies E,” stop and draw a diagram.

The Acid Test

If you need more than two sentences to describe a spatial or relational concept, it probably needs a visual.

Types of Diagrams

Architecture Diagrams

Show the major components of a system and how they connect. Keep them high-level. Label every box and arrow. Use consistent shapes: boxes for services, cylinders for databases, clouds for external systems.

Sequence Diagrams

Show the order of interactions between components over time. Excellent for API flows, authentication handshakes, and distributed system communication.

Flowcharts

Show decision logic: if this, then that. Good for explaining algorithms, error handling paths, or configuration choices.

Entity-Relationship Diagrams

Show how data objects relate to each other. Essential for database design chapters.

Before/After Diagrams

Show system state before and after an operation. Effective for teaching about data transformations, migrations, or refactoring.

Creating Diagrams

Tools

Choose tools based on your needs and publishing format:

  • Mermaid: Text-based diagram syntax. Renders in many Markdown environments. Excellent for version control since diagrams are plain text.
  • Draw.io (diagrams.net): Free, browser-based diagramming tool. Exports to PNG, SVG, PDF.
  • PlantUML: Text-based, great for UML diagrams. Integrates with many IDEs.
  • Excalidraw: Hand-drawn style. Gives a friendly, sketch-like feel.
  • Lucidchart/Figma: Professional tools for polished diagrams.
  • Pen and paper + scan: Surprisingly effective for early drafts and informal books.

Design Principles

  • Simplicity: Show only what is needed. A diagram with 20 boxes and 40 arrows teaches nothing.
  • Consistency: Use the same visual language throughout the book. If a rectangle means “service” in Chapter 2, it should mean “service” in Chapter 10.
  • Labels: Label everything. Unlabeled arrows and boxes force the reader to guess.
  • Direction: Maintain consistent flow direction. Left-to-right or top-to-bottom. Don’t mix.
  • Color with purpose: Use color to highlight or group, not to decorate. Ensure your diagrams are still readable in grayscale (for print).
  • Numbering: For complex diagrams, number the steps and reference them in the text.

Accessibility

Some readers are colorblind. Some read in print (black and white). Some use screen readers. Design diagrams that work without color:

  • Use labels and shapes, not just colors, to convey meaning.
  • Provide text descriptions of key diagrams.
  • Use patterns (dashed, dotted, solid lines) in addition to colors.

Tables

Tables are underused in technical books. They are excellent for:

  • Comparing options: Framework A vs. Framework B feature comparison.
  • API reference: Endpoint, method, parameters, response format.
  • Configuration options: Setting, default value, description.
  • Decision matrices: When to use X vs. Y.

Table Design

  • Keep tables concise. If a table has more than 7-8 rows, consider whether all rows are necessary.
  • Use clear, short column headers.
  • Align numerical data to the right.
  • Bold or highlight the recommended or default option.

Callout Boxes and Admonitions

Callout boxes draw attention to information that stands apart from the main flow:

  • Tip: A helpful suggestion. “Tip: You can speed this up by enabling caching.”
  • Note: Additional context. “Note: This feature was introduced in version 3.2.”
  • Warning: Something that could cause problems. “Warning: This operation deletes data permanently.”
  • Info: Background context or tangential information that enriches but isn’t essential.

Guidelines

  • Use callouts sparingly. If every page has three callout boxes, they lose their impact.
  • Keep callouts short — 1-3 sentences. If it’s longer, it belongs in the main text.
  • Place them near the relevant content, not pages away.

Formatting for Readability

Code Formatting

  • Use monospace font for all code, commands, file paths, and technical identifiers.
  • Syntax highlight code blocks for the appropriate language.
  • Keep code lines under 80 characters to avoid wrapping in print formats.
  • Number lines in long code listings for easy reference.

Text Formatting

  • Bold for key terms when first introduced, and for emphasis.
  • Italic for book titles, new concepts, and slight emphasis.
  • Code font for inline technical terms: function names, variable names, file paths, command-line flags.
  • Use bullet lists for unordered collections of items.
  • Use numbered lists for sequential steps or ranked items.

White Space

White space is not wasted space. It gives the reader’s eyes a break and makes content scannable. Use:

  • Blank lines between sections.
  • Space around diagrams and code blocks.
  • Short paragraphs (3-5 sentences).
  • Lists instead of dense paragraphs when presenting multiple items.

Consistent Conventions

Establish formatting conventions and document them for yourself:

  • How do you format file paths? (/etc/config.yml or /etc/config.yml?)
  • How do you format keyboard shortcuts? (Ctrl+C or Ctrl+C?)
  • How do you format menu items? (File > Save or File > Save?)
  • How do you format variable names? (myVariable or myVariable?)

Whatever you choose, be consistent.

Screenshots

Screenshots are sometimes necessary — for GUI-based tools, web interfaces, or IDE configuration. But they come with significant downsides:

  • They age badly: Any UI update makes your screenshots wrong.
  • They are expensive to maintain: Re-capturing screenshots across multiple platforms and resolutions is tedious.
  • They are hard to search: Readers cannot search text within a screenshot.

When to Use Screenshots

  • When the visual layout of a UI is essential to understanding.
  • When the exact visual output matters (charts, dashboards).
  • When describing a process that involves clicking through menus.

When to Avoid Screenshots

  • When a text description or a short list of steps would suffice.
  • For terminal output — use formatted text blocks instead.
  • For configuration — show the file contents as code.

Screenshot Best Practices

  • Crop tightly to show only the relevant area.
  • Annotate with arrows or numbers to highlight what the reader should look at.
  • Include alt text for accessibility.
  • Use a consistent screen resolution and theme.

Key Takeaways

  • Use diagrams for architecture, data flow, sequences, and relationships.
  • Keep diagrams simple, labeled, and consistent throughout the book.
  • Use tables for comparisons, references, and option lists.
  • Use callout boxes sparingly for tips, warnings, and notes.
  • Establish and follow consistent formatting conventions.
  • Use screenshots only when visual layout is essential; prefer text otherwise.
  • Design all visuals to work in grayscale and for accessibility.
← Chapter 5: Code Examples and Exercises Table of Contents Chapter 7: Editing and Technical Review →

>> You can subscribe to my mailing list here for a monthly update. <<