> if something is so complicated it can only be understood with a picture, it's too complicated
Absolutes like this contribute significantly, depending on the perspective they're spoken from, to the anti-intellectualism in our society today, or to a culture of elitism.
For the first, some things are complex, and that complexity is part of the real-life systems and structures they have to interface with or represent. Explaining complex things with a diagram can be an extremely effective method for making what might otherwise require a very high cognitive load much easier to process.
And for the second, if someone needs a diagram to understand something complex, it's not because they're stupid, and insisting that everything worth explaining can—and must—be explained in text only does them a disservice.
It seems like a good rule of thumb though. Here's a diagram of the 11 different tools you need to study to create an installer with WiX, which takes literally thousands of lines of XML: https://documentation.help/WiX-Toolset/tools.html
By contrast, WiX# provides a complete code sample that specifies a complete installer in less than 20 lines, with no diagram necessary: https://github.com/oleg-shilo/wixsharp
You seem to be arguing that the existence of one bad diagram and one (related) good text explanation proves that, in general, needing a diagram is bad, and being able to explain something succinctly and clearly in text proves the merit of the thing being explained.
I...do not feel that this follows in any way, either as an absolute or as a rule of thumb.
In my personal opinion as a user, usage of WiX is extremely complicated (requiring multiple different tools, thousands of lines of XML, understanding of the incomprehensible MSI database format as well as the multiple levels of inscrutable macro substitution WiX puts on top of it, and so on). The documentation presents a diagram of the 11 different tools involved (which I'm not saying is a "bad diagram").
Usage of WiX-sharp (which wraps and hides the mess decribed above) is so simple that a complete sample project is just a few lines of code, as shown in the README. There is no diagram because none is needed.
This is consistent with (but doesn't prove as a general rule) the idea that "if something is so complicated it can only be understood with a picture, it's too complicated"
> to the anti-intellectualism in our society today, or to a culture of elitism.
It wasn't meant to be an absolute, it is just a rule of thumb, and for me. I expressed it that way for rhetorical purposes.
I don't think retreating to real language is anti-intellectual; but you may be right that it's elitist to mistrust stories told in pictures. Anti-intellectuals mistrust stories told in words.
I find that I write most diagrams for myself as a reader. It takes much less time to get an overview some logic I have not touched in a while when there is a diagram to start with. Once I remember the big picture I dig deeper via the code.
Absolutes like this contribute significantly, depending on the perspective they're spoken from, to the anti-intellectualism in our society today, or to a culture of elitism.
For the first, some things are complex, and that complexity is part of the real-life systems and structures they have to interface with or represent. Explaining complex things with a diagram can be an extremely effective method for making what might otherwise require a very high cognitive load much easier to process.
And for the second, if someone needs a diagram to understand something complex, it's not because they're stupid, and insisting that everything worth explaining can—and must—be explained in text only does them a disservice.