Monodraw

Bought this couple months ago, and am now always looking for more ways to include this for inline-documentation.

the fact i can export to clipboard and re-import it and reconstruct all the shapes etc. almost flawlessly is such a big win.

On one hand, this could provide a lot of value as some things are just plain hard to explain using only words. On the other hand, aren't you worried about when someone else comes along and needs to update one of those comments? If they're not aware of this tool, it's either going to be incredibly tedious or simply not going to happen.

Add a one line comment stating that it was edited by monodraw.

Since they're text files, you can also say "Please copy to a ASCII diagram editor and update there (e.g. Monodraw, asciiflow, etc.)".

Sounds super interesting, where do you put these diagrams ?

It's an issue I'm seeing even for comments touching too much on algorithmic stuff. To take a somewhat common example, if you were dealing with a credit card payment flow, where would the explanation of how a transaction goes through a few states asynchronously, which all trigger a webhook callback ?

Obviously the people working on the code need to be aware of that, so documentation is somewhere needed. I've seen people put whole blocks in class headers, other sprinkle it all inside the code, personally I ended up moving it outside of the code. Where would you put it?

Looks like Monodraw a mac only BTW. That should be fine if macs are mandatory for all the devs on a project, but it would otherwise create a kinda weird situation.

Absolutely love monodraw for diagrams in documentation! All of the diagrams for Oban and Oban Pro are done this way:

Job Lifecycle: https://hexdocs.pm/oban/job_lifecycle.html

Composition: https://oban.pro/docs/pro/1.6.4/composition.html

As the other commenters put it, i dont think this is a huge issue. I usually use this for architecture level diagrams, and that shouldn't change often/at-all. In-case it does change, doing a new diagram is perfectly in-scope of whoevers working on that.

> am now always looking for more ways to include this for inline-documentation.

same lol. here is a blog post of mine where I used them - https://avi.im/blag/2024/disaggregated-storage

I had to convert them to images because I couldn't get to working with Hugo, static site generator

I personally just throw them at the top of my files as long block-comments, or sometimes inside/around very heavy functions. For example i often add little diagrams for when dealing with some bit-fiddly logic parts to easier visualize the bit-layouts. But for architecture, either a whole text-file for it or at the top of the module

Sidenote: thanks so much for taking the time to write the Oban docs. I'm a big user (and fan) of Oban, and the docs are fantastic.

Thanks! Do you deal with the logic getting split/shared around the code ? For instance on the credit card example there will be probably be one central class (the transaction class?) but you'd need to know the whole logic in the card registration part or the webhooks as well. I guess you don't stick a diagram everywhere ?