If UML or other structured ways to define system gist was 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 any 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 with. Maybe the developers were obligated to write other prose documents that act as the documentation of the produced software.
To document 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 really 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 documentation for existing software systems. Instead they have a tendency 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 expect that the documentation is complete or correct.
Prose documentation of system-gist is by the reasons stated above almost never used for anything except making the stakeholders feel a bit safe – like life jackets on an airliner – that fly 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 knowhow that is the system gist is what I would describe as “invest in the team”.
Let the skilled and motivated software developers solve things with their talent and memory. Let the collective team memory be your knowhow 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 place in them.
Still I have seen many cases where this strategy over the years create 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 now are left on their own to decide where the resources should go – into system gist or into modernity or maybe into fashion. They will soon lose the managements 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 take on what is modern and what is fashionable this year – or was – last year.