Value of Diagrams (Was: Which came "First"?)

[Ben Kovitz <apteryx -at- CHISP -dot- NET>]

John Posada queried:

>Hi, guys...any opinions/facts/rules for the placement of the word
>"first" in the following sentence?
>
>"If you want to configure more than two XXXs when none exist, you must
>first grow two XXXs, then grow the additional XXXs."
>
>or
>
>"If you want to configure more than two XXXs when none exist, you must
>grow two XXXs first, then grow the additional XXXXs."

I like the "first" one.  I mean, the one that came first.  The one that you
listed first.  Ok, this one:

"If you want to configure more than two XXXs when none exist, you must
first grow two XXXs, then grow the additional XXXs."

The reason is that in this version, the word "first" stands out a bit more.
That is, the flow is a bit less smooth, so I'm thinking that a reader would
be less likely to slide by the word "first" without noticing it.

If it's really important that a reader understand this, I'd add a graphic
showing that you can't get to C except from B, and how to get from A to B.
It might not say anything that the sentence doesn't say, but the graphic
would make it stand out more, so that someone skimming through the manual
would see it.  Of course, such a graphic would also be a fine place to add
more content than is in the sentence, if the XXXs are also in other
relationships that the reader must understand.


I think a simple diagram should be the first option to examine, whenever
you find that a set of relationships is a bit tricky to express in a
sentence.  In fact, it seems that three "things" with two or more distinct
"relationships" between them is close to the cut-off point for what you can
easily communicate in text.  (It varies a lot depending on the content, of
course; I probably wouldn't bother with a diagram for the preceding
sentence--though, you know, it might help.)

A friend who is in law school recently told me about "the most difficult
concept covered this entire semester."  This concept is supposed to be so
incredibly complex and tricky that they don't even expect practicing
lawyers to get it right.  A funny thing about lawyers and law schools,
though, is that they almost never draw diagrams.  Everything is text, text,
text.  Well, four hours of interrogation later, I learned the concept and
slapped out this diagram: http://www.chisp.net/~apteryx/privity2.gif .
(The diagram requires commentary to understand, and I didn't spend any time
tuning it aesthetically.  It's just there to make my point about diagrams.)
It's got six "things" and eight pertinent relationships.  In other words,
it's no more complex than the stuff programmers deal with almost every day,
and in a diagram it's not especially difficult to understand.  And yet,
just because it's taught entirely in words, its complexity is considered by
some lawyers to border on the mystical.

Finally, a less obvious and much-neglected function of graphics is simply
that they put *huge* emphasis on whatever is in them.  I think they're a
much better technique for announcing that something is especially important
than little remarks like "NOTE:" or "IMPORTANT!".  Emphasis is the main
reason I'm thinking that a graphic might help for John Posada's situation,
since the complexity is only right at the borderline (three states and two
types of action connecting them).  But I've been thinking a lot about
diagrams lately and just wanted to bring this up. ;)

--
Ben Kovitz <apteryx -at- chisp -dot- net>
Author,  _Practical Software Requirements: A Manual of Content & Style_
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz


 From ??? -at- ??? Sun Jan 00 00:00:00 0000=