The UML diagrams are a good example of the problem I am talking about: they carry too much (unessential) information - you can draw the boxes in too many ways.

Hm, I am still not sure I understand your point:

I mean the UML spec as its whole is quite a mess, sure, which is why it is not so relevant anymore. But very specific defined UML diagramms, like UML class diagramms - carry just the essential information for me. Like class name, member names with types and connections showing me where this class interfaces or inherits from. I really liked that and preferred it much over the same information in code representation.

But doing it by hand was just not worth it for me.

Diagrams are visual and need many more bites than the code they are created from. Just compare a gif of a diagram and its description. The additional information is how the boxes look - are they big or small, colors, what font is used, what margins are there, and many more. Describing it I use text and divide the differences into categories - but maybe I should just write that for the visuals you need information for each pixel.

When you interpret the diagrams you map them into a much smaller space of meanings. In that process you throw out a lot of that visual information.

Ah, now I understand what you mean. It is certainly true, that there is additional information in a diagram.

But - most of that information is just visual help to transport the raw information - to enable you to decode the information (which is what this is all about, as decoding code is mental work).

The x y position of a uml class diagram for example, is irrelevant in terms of raw data, but it makes a difference to the brain, of whether one diagram is centered or in some corner. Likewise all the other information, like color etc.

They are simply there to help you understand the main information. So I do not think they carry unessential information. If the color of a diagram helps get the information across - meaning it makes it easier for the reader to understand the main information - than that information might be not essential, but still important. Whether that works, depends of course on the diagrams and tools and how they get used. Again, this is the hard part.

> Diagrams are visual and need many more bites than the code they are created from.

Only if you store them inefficiently.

> Just compare a gif of a diagram and its description.

A bitmap image (GIF or otherwise) is an inefficient way to store a diagram. For a purely semantic diagram, the source it represents minus anything not actually represented in the diagram is sufficient; if you have additional presentational information you need that, too. For a diagram-specific format, something like graphviz or mermaid source is a possible representation.

What you are saying is that UML is not really visual but rather a kind of text. This got me thinking. The text I am writing here is also on one level just text - but I see it as a visual representation of black dots on a white background. But I think the point of diagrams is to be really visual and of text to be text.

In my experience, generating documentation from code is a fools errand (unless it's API documentation). The key (and hard part) to documenting existing code is to understand which details emphasize and which ones can be left out. I read documentation in order to more quickly understand a software component than I would by just reading it's code.