All 5 books, Edward Tufte paperback $180
All 5 clothbound books, autographed by ET $280
Visual Display of Quantitative Information
Envisioning Information
Visual Explanations
Beautiful Evidence
Seeing With Fresh Eyes
catalog + shopping cart
Edward Tufte e-books
Immediate download to any computer:
Visual and Statistical Thinking $5
The Cognitive Style of Powerpoint $5
Seeing Around + Feynman Diagrams $5
Data Analysis for Politics and Policy $9
catalog + shopping cart
New ET Book
Seeing with Fresh Eyes:
Meaning, Space, Data, Truth
catalog + shopping cart
Analyzing/Presenting Data/Information
All 5 books + 4-hour ET online video course, keyed to the 5 books.
Communicating software design

This question was inspired not only by the content of the "visual means of discovery" and "Quality of software, software processes and the UML" threads but also by their proximity. My concern seems to span both those topics.

When I attended the Tufte seminar in Houston (some time ago), my goal was to gather techniques for more clearly representing a computer program as it is being created and as it is or has been coded. Here is the problem as I see it:

A program is a combination of algorithms and data structures upon which the algorithms operate. Both components of a program have representations that are functions of time. While the program is being created, the capture of these representations (mentally, visually/graphically, verbally, in code, etc.) *is* the mechanism of creation. It is also the mechanism by which the programmer communicates the work to be (or that has been) done to himself, to users, to other programmers, and to managers. While the creation process is happening, the captured portion of these representations is necessarily incomplete; and, the next incremental addition depends strongly upon the captured portion having been represented well. Hopefully, the iterative, incrementally additive capture process will converge in an acceptable amount of time and yield a correctly working program that meets expectations.

As an independent software development consultant, i.e., someone who enters a new environment with the expectation of creating a complex, schedule- and budget-constrained mission-critical program that is to be left entirely in someone else's hands, this representation issue is important to me. For example, it would be unethical to leave a customer with insufficent information to maintain a program in my absence. Generally, use of formal tools (e.g., UML) won't fit schedule or learning-curve constraints. Often, any non-verbal representation of software is met with resistance until schedule and budget issues become overwhelming. To make a long story short, typed text plus pencil and paper diagrams are usually the tools of choice. The question is this:

Has your experience with presenting complex but relatively static data allowed you to derive any techniques, best practices or rules of thumb that (1) promote/ensure complete presentation of an idea or set of data, or (2) provide positive indication that a presentation is not complete or has additional as yet unrepresented portions?

By the way, some of the concepts presented in your seminar were, in fact, immediately useful in this context and for purposes of designing a user interface. It was money well spent.

-- Samuel Denard (email)


Samuel, I've been doing some work pertinent to your query. I work on documenting GIS (geographic information system) software.

In a book project two years ago, I worked on documenting and visualizing several thousand COM software interfaces used in our software development. These software interfaces are accessible to our customer for customizing applications, so we had to devise an clear and efficient presentation of our software architecture.

These are some thoughts and lessons we learned:

- Just as maps can be made at various scales to represent different levels of detail and representation types, use at least two "scales" of presentation for documenting a substantial software system. Develop a single generalized presentation showing the entire structure of the system at a glance and supplement this with a suite of diagrams showing the full details of the software interfaces.

- It's better to devise a new, simple notation for your system rather than trying to apply UML. Start with just boxes, text, and lines and enhance your notation only as necessary. Visio is ideal for this. We've found that UML is intimidating to many people and by it's design, UML can over-emphasize certain aspects of design (such as inheritance) and obfuscate others (UML is not really suited to component architectures).

- The act of creating a diagram, whether on paper, whiteboard, or Visio, will directly influence your design. Just as a map can uniquely reveal relationships between features, a good diagram of software structure will reveal the structural patterns in your system. You will discover and ponder these patterns, then apply them across your system. (really!)

- This might a bit much for a small shop, but if practical, automate the generation of diagrams. I've found it extremely powerful to programmatically create diagram elements with custom applications using VBA (Visual Basic for Applications) inside Visio. I've written several applications that programmatically interrogate the IDL for a DLL and create diagrams in Visio. The general approach is not to automate the structural relations, but the objects, and then lay them out in Visio.

- It is extremely difficult to understand software code from print-outs. But if you make a poster of the structure, then this will become the focus of group interaction and discussion and is a powerful catalyst for driving design iterations. Management loves these posters, because even they can understand them. We've found that creating these diagrams to be essential for the design process and enhancing software quality. Creating these diagrams using automated Visio tools is mandatory for our software development team.

Presently, I'm working on a new book documenting best design practices for geographic databases. In this work, instead of visualizing software structure, we are presenting database schemas, together with conceptual illustrations showing concepts such as how streets are associated with address ranges, how stream networks are connected, and how land parcels tesselate and nest into administrative regions.

Again, I spent a fair amount of time up-front automating the presentation of schemas with Visio/VBA, but this has turned out to be a huge time saver. With this tool, I can construct a detailed E-size print of a schema diagram in a day. To see examples of database schema posters, go to www.esri.com and follow the links to Support > ArcGIS desktop > Data Models > 2002 User Conference Posters and download any of the PDF posters. (This part of our web site might reorganized soon, if the link sequence doesn't work, search for Data Models) Good examples are the Hydro Data Model, Land Parcel Data Model, Census Data Model, and 1:24k Basemap Data Model. (These are initially created in Visio, then sent to Adobe Illustrator via EPS, finished with conceptual graphics, and published as PDF)

When you look at any of these diagrams, you'll notice three levels of presentation that correspond to traditional database design cycle(conceptual > logical > physical). The conceptual design is presented as a stack of cartographic layers on the right. The logical design is shown as the detailed schema diagram that forms the majority of the poster. The physical design is shown as a representation of the structure as seen in the software user interface (the "Catalog view").

Email me if you'd like to see examples of the software interface diagrams.

-- Michael Zeiler (email)


The lead article in this month's "Rational Edge" - the on-line magazine for Rational processes and products - starts by quoting Dr. Tufte in "Envisioning Information." The article is the third in a series about modeling software systems.

http://www.therationaledge.com/content/jan_04/f_modeling3_bl.jsp

Another article in the same issue that caught my eye was about creating cartographies with the Rational products. I don't have access to any of the products, so I can't say if the approach is viable in the real world, but the idea of using object modeling to "map" both software and non-software systems is interesting.

http://www.therationaledge.com/content/jan_04/t_genericrose_ng.jsp

I don't know if one is required to have a user id to view the 'zine. If you have any trouble, email me and I'll forward a pdf to you.

(Believe me, I'm not promoting Rational products, and I'm less and less happy with The Rational Edge as it seems to be transforming itself into a long advertisement for the products.)

-- Andrea (email)




Threads relevant to business:
Narrative sparklines should replace one-at-time instantaneous performance readings.


Threads relevant to software:


Privacy Policy