UML in Software Development - how to not be taken seriously (or professionally)

Last week I received a requirements document that contained 42 pages of UML Use Case Diagrams. The document was useless – page after page after page of hangman sketches (although the scaffolding was yet to be built). It must have taken weeks for the Business Analyst to put the document together yet conveyed little useful information to aid in understanding the system yet alone allowing me to estimate a development timeframe.

Below I show some documentation containing a diagram for a chemical retrosynthesis (Woodward’s synthesis of strychnine of course). The information conveyed within the diagram is exceptionally clear to practising synthetic organic chemists, and me.

Here is some information taken from Butler’s superb book on Forensic DNA Typing. The diagram is clear, and again the information being conveyed is very clear to me too.

Here is some information from a publication on Algebraic Combinatorics and for those skilled in the art, the information conveyed is very clear and the diagram (digraph D) certainly helps in understanding how the values of M(D) are derived.

The single point to note above is that the language being used is the domain language; in the field of mathematics, it is maths, in the field of chemistry, it is chemistry, in the field of DNA typing, it is also the domain jargon. The diagrams included above provide a lot of useful information. No attempt has been made to contort the content into UML diagrams taking away the meaning of the information being conveyed, whilst at the same time introducing jargon and diagrams that are unfamiliar to the reader.

Now enter Software Architecture and Development. Here are a few of diagrams and images commonly seen in Software Development, a UML Use Case diagram with three partial hangman/stick-men diagrams, some lines connecting oblongs that mean something,  and some childish stuff with images of coffee beans and cups. Sometimes the technical diagrams even include a cloud, but it does on occasion get even more ridiculous. And as for the new technical jargon, Actor, really? Someone needs to grow up!

Step back and ask yourself whether you should take anyone seriously were they to produce technical IT documentation containing an out-of-context sketch of a rabbit, a toad, a coin, a sketch of Freddie Mercury, or a currywurst? How about technical IT documentation that contained partial hangman/human stick-man diagrams (that look like they have been drawn by an 8 year old but likely written by professionals costing thousands of pound/euro/dollar’s), and some joke gone too far about coffee with images of beans and cups (or brightly coloured flood-filled rectangles that are meant to indicate application layers or tiers)? Of course you shouldn’t take anyone seriously presenting any of this information, yet some people do (and some don’t). It is quite sad.

None of my argument is about documentation that is meant to represent things at a high level vs. a granular level of detail, nor that UML is the language of the software developer or business analyst (and it isn’t) that has to be accepted warts and all including these puerile diagrams. It is about being professional, and including hangman diagrams and images of coffee beans and clouds in a technical document written by a professional is far from professional. Furthermore I see no benefit in a modelling language (if UML is really a modelling language, or just something that is called a modelling language as part of the sales job so it can be included on your CV) that causes everyone, business stakeholders and software developers, grief, by dumbing down the content to the point where it is uselessly expresses what information it does so badly. So much more information is required than what can be presented in a UML Use Case Diagram, and my argument is that if you have to produce a few paragraphs of text fleshing out what the diagram is supposed to convey, don’t draw the childish diagram to start with. In Microsoft Word you can easily search for text too; you cannot search for hangman diagrams!

Common Sense has been lost in Software Development (and Business Analysis). It is no wonder that respect for the profession has been lost too. And yes, I might have my grumpy old man hat on today, but that doesn’t necessarily mean that I am wrong!

— Published by Mike, 07:46:12 24 May 2017 (CET)