Re: diagrams

Subject: Re: diagrams
From: Ben Kovitz <bkovitz -at- nethere -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 22 Apr 2002 06:42:19 -0700


Jennifer Maitland wrote:

> I'm using MS Visio to create a very complex system map diagram consisting of
> both a technical and functional overview. Until now, I haven't really
> applied a whole lot of thought or planning to creating diagrams and by using
> the typical Jennifer approach (jump in, eyes closed, thoughts of success and
> perhaps even learning a thing or two) I've been able to get by with the few
> insignifcant diagrams I've been asked to make. I am aware that there are
> 'rules' and schools of thought behind creating certain types of diagrams,
> but until now I hadn't actually been asked to document anything that
> required diagrams of much complexity.
>
> However, the concepts behind the software I'm documenting now is more
> complex than anything I've ever documented, and I think it's high time I
> took a more organised and responsible approach to diagrams as I know there
> are likely volumes written on the subject.
>
> Can anyone recommend a few good resources to use as a starting point? Books
> and URLs are appreciated, thanks.

The usual Jennifer approach sounds just fine to me!

I'd be skeptical of any "organized" or "systematic" approach to making
diagrams. Making diagrams is a craft in which you find a unique order
within a unique chaos. Out of the infinity of possibly relevant
pieces of information, what should be included? What should be
omitted? What relationships should be emphasized, and how should they
be emphasized? Which of the infinity of possible ways to break down
the information should you follow? There can be no simple, *a priori*
answers to these questions. You just have to wrestle with the unique
whole you're dealing with, and let your aesthetic sense navigate you
to a harmonious way of fitting all the parts together.

A systematic approach--anything beyond "make a list of stuff that you
might want to put in the diagram, start drawing, evolve, and don't be
afraid to start over with a radically different approach"--can only
apply to things that are basically the same each time.

If you're worried about being irresponsible, consider this: what is
the cost of sketching a diagram, throwing it out, and starting over
because that diagram's flaws gave you a better idea, and what is the
cost of delivering a nearly useless, procrustean diagram that you made
with no backtracking by applying a systematic method that gave you
answers in advance of the data? The main costs are your and your
users' time, and the main factor that makes the diagram useful is
understanding. You learn faster by making mistakes than by trying to
avoid mistakes, so the truly professional approach is to make as many
mistakes as possible as early as possible.

That said, the three classic books by Edward Tufte have all been great
sources of inspiration for me when making diagrams:

The Visual Display of Quantitative Information
http://www.amazon.com/exec/obidos/ASIN/0961392142

Envisioning Information
http://www.amazon.com/exec/obidos/ASIN/0961392118

Visual Explanations
http://www.amazon.com/exec/obidos/ASIN/0961392126

The second one has given me the most help in making diagrams for
software user's manuals. The first one is aimed more at describing
quantitative relationships, but its notion of "data-ink ratio" has led
me to a lot of simplifying ideas for diagrams about all kinds of
things. All the books are short and teach mainly by example,
including examples of bad diagrams that the author converts into
excellent diagrams. Each covers only a handful of principles that
apply broadly, without getting into the "a priori" trap.


Ben Kovitz
Author, Practical Software Requirements: A Manual of Content & Style
http://www.amazon.com/exec/obidos/ASIN/1884777597
http://www.manning.com/Kovitz

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Free copy of ARTS PDF Tools when you register for the PDF
Conference by April 30. Leading-Edge Practices for Enterprise
& Government, June 3-5, Bethesda,MD. www.PDFConference.com

Are you using Doc-to-Help or ForeHelp? Switch to RoboHelp for Word for $249
or to RoboHelp Office for only $499. Get the PC Magazine five-star rated
Help authoring tool for less! Go to http://www.ehelp.com/techwr

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit
http://www.raycomm.com/techwhirl/ for more resources and info.



References:
diagrams: From: Jennifer Maitland

Previous by Author: A trip to IKEA
Next by Author: Re: A trip to IKEA
Previous by Thread: diagrams
Next by Thread: Re: diagrams


What this post helpful? Share it with friends and colleagues:


Sponsored Ads