Training:What if UML was forbidden

If UML or other structured ways to define system gist were forbidden – what would happen then? Maybe UML need not be forbidden – the effect would be the same if UML simply was not used.

Well, the system gist still exists – even if it is not explicitly documented. It must be extractable from the source code of any running system since the system is a transformation of the system gist no matter how that gist was captured in the first place.

Maybe the system gist is held in documents that outline requirements or prose text that describe scenarios that the system should solve or support. Maybe the developers were obligated to write other prose documents that act as the documentation of the produced software.

Documenting software is boring compared to coding for any developer. Code can be compiled and type-checked so that bugs in it can be removed. Code can also be executed and further tested to ensure that the idea we wanted to cover is covered. Documentation does not work that way.

Most likely any existing documentation is filled with bugs beyond belief since the process of verifying lacks compilation and testing. Since developers suspect this, developers seldom trust and seldom consult the documentation of existing software systems. Instead, they tend to go to code. If the only option is prose documents, they are probably correct. Even if the developer finds information in the code – it is important to remember that the code is just the original developer’s interpretation of the requirement – and this need not be equal to the requirement. Software tools and libraries may follow other rules – but when an experienced developer is confronted with a software system he or she very seldom expects that the documentation is complete or correct.

Prose documentation of system-gist is, for the reasons stated above, rarely used for anything except making the stakeholders feel a bit safe – like life jackets on an airliner that flies over land – it was never intended to help anyone – but the stakeholders want it so we provide it.

Another way I have come across to protect and keep the know-how that is the system gist is what I would describe as “invest in the team”.

Let skilled and motivated software developers solve things with their talent and memory. Let the collective team memory be your know-how and documentation of the system gist.

This is the common way for most businesses that produce software that I have come across. I argue that this is not a strategy. It is an abdication of ownership and control. Developers might not see this as a problem at first since they take pride in the trust management places in them.

Still, I have seen many cases where this strategy over the years created a chasm between the ones that know (developers) and the ones that make decisions (management) – it usually ends with a collapse that benefits no one. Since developers are now left on their own to decide where the resources should go – into system gist or modernity or maybe into fashion, they will soon lose the management's trust since management lacks control and does not understand why the developers chose to prioritize the way they do.

Nevertheless, this is commonly how small and midsized businesses handle their software investments today. Let the code speak for itself – there is no other representation of the ideas within the software than the code itself. The very same code that is strongly flavored by the team members takes on what is modern and what is fashionable this year – or was – last year.

See: Luckily UML is Not Forbidden