On this page

Guidedog / Documentation 0.2.0

Diagrams that explain

Choose a diagram for a question. A flow chart explains a choice. A block diagram explains responsibility. A sequence explains ordering. A graph explains relationships. Use prose when it answers the question more directly.

A flow chart

Fig. 3 Capacity is checked before storage is borrowed or grown.

The drawing names the owner at the growth step. It does not suggest that the conversion core allocates. This distinction is part of the contract.

Author a graph

.. graphviz::
   :caption: Parsing precedes resolution.
   :alt: The source becomes a tree, then references are resolved.

   digraph pipeline {
     graph [rankdir=LR, bgcolor="transparent"];
     node [shape=box];
     "source" -> "tree" -> "resolved tree";
   }

graphviz, graph, and digraph are built in. Guidedog renders them through Graphviz. HTML receives an SVG asset. PDF embeds the rendered drawing. Both use the same graph source.

Make the result legible

Keep node labels short. Explain a longer rule below the drawing. Prefer one direction for the main path. Label a return edge with its condition. Use shape and text as well as color. A print reader may have no color at all.

Supply alternative text and a caption. Test narrow browser windows and the PDF page. If a diagram needs tiny type to fit, split it into two drawings. See Images, video, audio, and downloads for image and figure sizing.