Software design is a process. It is a process of taking one abstraction – a business oriented model, and constructing a different abstraction – a technology oriented model.
Since there are many different technology paradigms, the technology oriented model differs based on the paradigms selected. The business oriented model differs by business, and the problem or value proposition. Part of every good design process is to decide how to represent or document each of those models.
For the most part, software design metthodologies have been selected because they help the developers represent the models that are in play, in ways that reflect the technology paradigms that are in use. Each methodology has commended some set of artifacts and sequence in developing, reviewing and revising those artifacts (e.g. Flowcharts, dataflow diagrams, uml class diagrams, data dictionary, data model, etc.).
Enter the antipattern:
In my experience, different organizations have used these methodologies and produced these diagrams with varying amounts of rigor. Somewhere along the way, auditors who are charged with proving that capital spent on software development actually resulted in a depreciable software asset decided that reviewing the artifacts of the software development life cycle (SDLC) were a good way to do this.
In public stock corporations, these audits are now required by law. Since the enactment of this law, known as Sarbanes-Oxley many large coprorations that engage in developing software products to be used as assets in the operation of their business, require that the documentation produced out of their SDLC are designed to pass these audits. Many of them have produced templates that are designed more to pass these audits then to help software developers capture the essence of the abstract models and prepare to build software.
When the developers who had less rigor in their design practice originally, are confronted with these document templates, their already ad hoc design process simply conforms to the template that they are presented with. This conformation of a process to a documentation template, without contemplating whether there is an appropriate methodology in place, or whether the template logically represents the essentials of the specific design being contemplated we have an anti-pattern.
Document driven design belies a focus on meeting audit requirements through our design documentation, rather than focused on articulating what it means to produce software capabilities. Similar antipatterns can manifest themselves in any aspect of our practice, where process compliance is more important that work product. Management's insistence on process compliance as a means to improve quality, moves us rapidly towards least common denominator solutions. However, it is inherently measurable, and easy to detect failures. It cannot, however, help you detect opportunity cost, or missed innovations, or other work product that was ignored, while maintaining process compliance.
Document driven design and similar template driven practice antipatterns often use the phrase "Best Practice" to rationalize their existence. But the tend to institutionalize a one-size-fits-all mindset, and with any best practice, what is best for some may not be suitable for all.
I am not suggesting that we eliminate design documentation, nor am I suggesting that we should not use document templates of some kind. Design doc is important both to clearly articulate design decisions we have made, and to help those who come behind understand how we got here. Templates are a useful product, for any repeatable process. However, templates must be aligned with the established repeatable practice, and if no practice is established, then all templates are simply taking the place of established repeatable practice. Those who create a document template should publish a process guide, to explain how their template aligns with a specific practice, or how it can be used by practitioners of alternate practices. The point of templates is to give someone responsible for documentation a leg up, or a head start. But often we are just providing an easy out, or an alternate version of chaos.
The next time you are confronted with a set of process documentation templates, ask yourself if you know how they align with the process you are performing. If you don't and are tempted to discern the process from the templates, then you are entering a template driven practice antipattern… proceed with caution.
No Comments