4 ms·

I’m a big fan of diagrams as code but only when I’m doing them usually. Mainly because I usually start out with an idea of what I want then try to recreate it.

I’m a big fan of diagrams as code but only when I’m doing them usually. Mainly because I usually start out with an idea of what I want then try to recreate it. Usually that means I’ve had to read the entirety of the tool’s documentation end to end, and often I’m still bummed because the tool can’t recreate what I see in my head. But whatever, I’ll compromise. But a lot of people go the other way. They make the diagram out of what they know how to use, and so generally their diagrams-as-code diagrams lack the detail you’d find if they had created it with a WYSIWYG tool. But I hate WYSIWYG tools. Editing and versioning them is challenging.

bluGill 4y ago
I like WYSIWYG tools for a static system. However since I'm documenting a dynamic system that is changing all the time the tool needs to reflect the actual state of the system as it is now, not how is was 2 weeks ago. 20+ years ago I worked with a UML code generation system, so our diagrams reflected reality: you couldn't change the code layout except by using the WSIWYG tool. As such we always had correct up to date diagrams. It was great, every Monday the first thing I did was print the current diagram out and pasted it to my wall, then the rest of the week I'd refer to that all the time, but by Friday there were noticeable differences. Unfortunately such tools never caught on - in part because they have other limitations - but the diagrams were something I still miss.