Comprehensiveness is the enemy of comprehensibility – Martin Fowler
Martin’s quote may be the main reason why this preference was written into the Agile Manifesto…
Working software over comprehensive documentation
Obviously, it doesn’t say “Working software and no documentation“. I’d bet my house that Martin and his fellow colleagues who conjured up the manifesto intentionally stuck the word “comprehensive” in there for a reason. And the reason is that “good” documentation reduces costs in both the short and long runs. In addition, check out what the Grade-ster has to say:
The code tells the story, but not the whole story – Grady Booch
Now that the context for this post has been set, I’d like to put in a plug for Simon Brown’s terrific work on the subject of lightweight software architecture documentation. In tribute to Simon, I decided to hoist a few of his slides that resonate with me.
Note that the last graphic is my (and perhaps Simon’s?) way of promoting standardized UML-sketching for recording and communicating software architectures. Of course, if you don’t record and communicate your software architectures, then reading this post was a waste of your time; and I’m sorry for that.
It’s one thing to “bend” the UML to express a design concept that you don’t know how to express with the language, but it’s another thing to “break” it outright. By “break“, I mean drawing old-school, ad-hoc, single-symbol diagrams that all look alike and passing them off as UML class, deployment, activity, etc, diagrams.
By propagating broken UML diagrams out into the world in a sincere, but fruitless, attempt to establish a shared understanding among team members, the exact opposite can occur – mass confusion and an error prone, friction-filled development effort. Even worse, presenting the ad-hoc quagmire to customers and financiers who have a rudimentary education in object orientation and UML can cause them to question the competence of the presenters and the wisdom of their investment choice.
But hey, there’s nothing to worry about. Nobody understands or cares about the UML anyway. Thus, the ambiguity, inconsistency, and conflicts inherent in the design won’t be exposed (or ever traced-back-to) if schedule and cost disaster strikes.
All models are wrong. Some, however, are useful. – George E. Box
In search of economies of scale, centrally planned and controlled economies in nations and corporations tend to create monopolistic providers of goods and services. For example, in corporations, accounting, personnel, and R&D departments are usually deliberately organized as subsidized monopolies. They are subsidized in the sense that the users of their products or services do not pay for them directly; the supplying units are supported financially by funds that are allocated to them from above. The pool from which these funds are drawn is filled by a “tax” allocated from above to the units served. Monopolistic units that are subsidized are generally insensitive and unresponsive to the users of their services, but they are sensitive and responsive to the desires of the higher-level units that subsidize them. These higher level units are even more removed from the units served than the serving units. As a result, they are often unaware of, or unresponsive to, the needs and desires of the internal users of monopolistically provided goods and services. – Russell Ackoff (Ackoff’s Best: His Classic Writings on Management)
OK, time to practice my “bent” UML modeling skills and test your understanding with the class and sequence diagram pair below. The class diagram provides a structural view of a fictional Ackoffian system. The sequence diagram steps through an amalgam of behaviors in a world where monopolies rule. Any questions, comments, critiques, accolades, WTFs?
The figure below shows some text from the official Scrum Guide. It’s followed by a “bent” UML class diagram that transforms the text into a glorious visual model of the SPM players and their responsibilities.
In unsuccessful Scrum adoptions where a hierarchical command & control mindset is firmly entrenched, I’ll bet that the meeting is a CF (Cluster-f*ck) where nobody fulfills their responsibilities and the alpha dudes dominate the “collaborative” decision making process. Maybe that’s why Ramblin’ Scott Ambler recently tweeted:
Everybody is doing agile these days. Even those that aren’t. – Scott Ambler
D’oh! and WTF! – BD00
Of course, BD00 has no clue what shenanigans take place during unsuccessful agile adoptions. In the interest of keeping those consulting and certification fees rolling in, nobody talks much about those. As Chris Argyris likes to say, they’re “undiscussable“. So, Shhhhhhh!