Years ago in school, before the days of CAD, I took a mechanical drawing class. Each student sat at their own drafting table and we learned formal techniques for professional-quality drafting with a pencil.
We learned to construct multiple views of a thing (top, side, perspective, etc.) that fit together proportionately to tell the whole story of the thing. We learned how to leverage the concept of “layers” to develop multiple drawings of the basic plan with focus on different types of detail for different audiences (foundation, plumbing, electrical, etc.). Taken together, these views and layers defined the requirement for builders.
In the software industry for development of complex integrated systems, many techniques and methods have been developed to communicate requirements to builders. Methodologies like Agile favor design as you go using smaller, more visible cycles, at the expense of documentation. But inevitably, complex integrated systems require some level of documentation: distributed teams, long project lifespans, and reusable components all need documentation in order to keep projects running smoothly.
Software itself is a very abstract thing – much more so than, for example, a house, which you can see as it’s being built – so having a concrete representation of the software before it is built (and after) can be valuable to ensure common understanding of the vision. Agile is attractive partially for this reason: it gives people something concrete to grasp more quickly.
By the same token, the abstract nature of software makes it very hard to create a useful representation of it. Here again, Agile is seen to save the day, by eliminating the need for representations of the system before building it. But we know that complex systems do require some level of documentation, even when they are developed using Agile methods.
In the world of architecture and construction, documentation in the form of architectural plans is developed by trained architects and engineers according to a consistent set of standards and regulations. A typical home, for example, might be built based on a set of 10 different floor plans – one each for foundation, electrical, plumbing, etc. The plumber works from the plumbing plan, the electrician from the electrical, and so on.
There may be one exterior perspective drawing that gives the buyer a vision of what the completed house will look like, but the plumber cannot reliably install pipes in the right place based on that perspective view. The plumber references the plumbing plan, with some reference to other plans to ensure correct interpretation, but you would not ask the plumber to build the house based on the plumbing plan.
The plumber might be more than happy to build the whole house for you, but you’re likely to end up with a whole lot of plumbing and not much house. In software, we have ‘plumbers’ building whole systems, with predictable results. As in architectural drawing, formal modeling and documentation techniques have emerged and evolved in the software industry.
Modeling formalisms such as Business Process Modeling Notation (BPMN), Activity Diagrams, Use Case Diagrams, State Machine Models, Sequence Diagrams, and Cause-Effect Modeling are available as arrows in our quiver for defining different kinds of expected behavior from different points of view. Unfortunately, these techniques are often not very well understood, even by the folks trying to use them.
There is a strong tendency to reject formal methods for abstraction through modeling (and disavow the need for them), because they are hard to execute and often not done well. But we know from thousands of years of designing and building complex structures that defining and elaborating plans at different layers of abstraction allows builders to build houses that we actually want to live in!
We know we can improve communication, simplify instructions, make validation of design more straightforward, and improve the likelihood of expected outcomes simply by using abstraction. In architecture, we are very good at using abstraction to make things concrete. In software, the formalisms and tools are available, but we as an industry are not skilled enough at using them yet.