Drawing Pictures
Pictures (specifically diagrams) are overly used in technical documentation, and many illustrations are themselves abstract and unfathomable. The problem is that those who cannot communicate in writing also lack the ability to communicate in pictures - so a bad picture is substituted for bad writing, and the result is no less unintelligible (and is, in fact, often worse).
Technical illustrations are, in a way, their own language, and a person must know how to read them in order to derive their meaning. Like jargon, they are understood by insiders, but unfathomable to others without explanation.
That said, there are instances in which an illustration can compliment (but not substitute for) text content, by providing a visual example of the location and interrelation of separate items in space and time. But instead of using a formal illustration (where each shape, color, etc. has a specific meaning), consider a simplified sketch that is readable to the layman without detailed explanation.
The author suggests a simple "data flow diagram" for communicating with laymen.
Why Data Flow Diagrams?
Requirements, by their nature, consist of a sequence of actions performed on one or more objects. They do not communicate a lot of detailed information, and are accessible to individuals who have no formal training in "esoteric diagrams."
In a data flow diagram, a circle represents an action or process, and arrows are used to show how the work flows through the multiple processes. Rectangles (boxes) represent external sources or receivers of data (connected by arrows to the process to/from which data is provided or received). Multiple paths through the flow can be based on conditions, which are indicated along the paths.
Because the diagram does not delve into specifics (what system does the processing, how the data is formatted, what the conditional tests are, etc.), it is simple, straightforward, and easily understood without formal training.
Basic Rules
The author describes some of the basic principles/rules that are geared toward keeping the diagram simple and understandable.
- The purpose of the diagram is to be simple and understandable - do not strive to make it precise or detailed to the detriment of simplicity
- Every process must have an input or an output (data must come from somewhere and go somewhere else)
- A process is a verb, not a noun (person, application, or system)
- Data is a noun, not a verb, and it cannot move or change by itself.
- Each piece of data must come from an identified source
- The diagram must begin and end with a data store or external
Summary and Detail Diagrams
To facilitate understanding, there should be a single diagram that summarizes the entire solution, end to end, with separate diagrams that get into greater detail about specific processes.
This can be done be either combining actions into processes (to summarize), or breaking down a process into more specific actions (to provide detail). This may also require being more general or specific about the nature and sources of the data.
To coordinate them, the author suggests using a decimal numbering system (3 => 3.1 => 3.1.1, etc.) and, if possible, to avoid going more than three levels deep.
To coordinate them, the author suggests using a decimal numbering system (3 => 3.1 =>Guidelines for Design Clarity
As noted earlier, a diagram can be just as convoluted and unfathomable as text. Tips to make them clear:
- Start at the top left and flow down and to the right
- Avoid flowing "upstream" at any point
- Align shapes in rows and columns to avoid visual clutter
- Make shapes the same size
- Be consistent in the space between elements
- Place connectors at only four points (north, south, east, west)
- Use only straight lines with 90-degree angles
- Use the same font (face and size) for all text
- Use shaded areas behind the shapes to group related items
Other Types of Diagrams
The author describes some of the other types of diagrams that may be useful in communicating with specific audiences, but I'm going to skip it. There are better sources of information of creating specific diagram types, and it's not germane to the purpose of the book (writing rules for a general audience, not a specific one).