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.
