Essential Software Design Documents

When it comes to documenting software designs, there are many practices ranging from a quick whiteboard sketch to fully specified UML models with OCL to tens of pages of written text. Here is what I found that worked best based on most projects that I have been part of:

1. Static Structure Diagram: this is a class, module, or package diagram. This diagram (though often it is more than one), shows the relationship between parts of the system at a given level of abstraction. The relationships shown include: containment, references, parameters, inheritance, and so on. Record on the diagram indirect and implied dependencies with a note.
2. Initialization Sequence Diagram: shows how the system is brought up from being on the disk into the operative memory and “ready to transact business” state. This diagram is part of the dynamic model of the system. It shows the order of messages sent or method invocations. Often also shows resources allocated to get up and running.
3. Shutdown Sequence Diagram: shows how to put back the system or component into the proverbial “bit bucket.” Must complement the initialization sequence diagram and demonstrate that the system is not loosing resources during its operation.
4. Sequence Diagrams, Activity, and/or State Diagrams for the key “business” of the system or software part. All other activities took place just to get ready to do the business of the system. Now it is time to get the business done. The key sequence diagrams show what the system does, how it provides the value that it is expected to deliver.
5. Brief Design Commentary to explain the “why” behind key structural and behavioral elements and decisions. This is usually one Wiki page that ties all other documents together into a coherent whole.

Each of these can be created at “every zoom level” in the system. This means that if you are developing a component-based system, then you would have this set of design documents for the system, subsystems, modules, and components. Within each you represent the unique concerns of each software part.

Read Applying UML and Patterns, 3rd. Ed., by Craig Larman for an in-depth course on how to do object-oriented analysis and design on an iterative software development project. As you do design more, review your results, learn from your mistakes, and over time you'll get better at it.

Resources

1. UML basics: An introduction to the Unified Modeling Language, from IBM developerWorks, 2003.
2. Allen Holub's UML Quick Reference. 2007.
3. Book excerpt from OOAD with Applications, by Grady Booch.
4. UML Modeling in Color, from Wikipedia.