So you used an ASCII drawing tool to draw these diagrams in text then took a screenshot of them and uploaded to your website? That seems like such a convoluted way to draw a few rectangles. Isn't there an easier way?

1. You can just “Save as” to PNG, it takes no time or effort.

2. I use to use Monodraw exclusively for making diagrams in source code, but over time I’ve become so comfortable with the tool, keyboard shortcuts, etc. that now I just use it for all diagrams. It’s a very nice tool.

The diagrams I am pasting in are usually like 80 x 40 chars and keep you from having to tab out into documentation. They don’t change often so they don’t create messy diffs. I don’t think that’s unreasonable. Nobody on my team seems to mind. I don’t think this is a problem and I’m having trouble understanding why you think it is.

If you’re wondering why I need diagrams in source code, then the answer is I usually don’t need them but it helps. The only project where they were game changing was where we were using Neo4j as a backend and being able to clearly diagram the data model was really helpful.

I don't really have much of an issue with it. It's got bad vibes by association. I find it a little annoying how much stuff is done with text, and this is just a small part of that.

Please don't do things like this that make it harder for people to read your comments.

Writing documentation is typically an addition to writing comments. They serve different purposes. That said, adding a diagram to a comment will only make it easier to read. It is an addition. It cannot make things harder.

If only it were true, that additions cannot nake things harder to read.

In this case, it is absolutely true. It is the difference between:

  // some comment

and

  // some comment
  // additionally see ./diagram.png

Diagrams are often useful tools for communicating information.

That's not the difference I'm talking about; I'm talking about the difference between

  // some comment
  // ... 25 lines of a diagram

and

  // some comment
  // additionally see ./diagram.png

Thanks! I’m sure they never thought of that!

Or maybe they did, and there are advantages and tradeoffs to any approach.

I’m sure your unique insight must be right, though.

You don't need to get so annoyed on someone else's behalf. I am just putting my opinion out there – specifically that I would prefer just an image file that is referenced from a comment. I'm sure this person knows what an image is; I was not trying to imply that they didn't.

Doesn't seem more convoluted than any other drawing tool to me. The UI of Monodraw appears to be pretty similar to "regular" drawing software.

In the second link, about the Smalltalk VM plugin, you can see is pre-formatted text in markdown.

In the Mapless guide, when I've kept it as text (as the first preferred way to have it done) it became challenging to make it work for all screen sizes and an image was the "good enough" approach for the case.

At least for the README, the diagram remains text in three backticks.

Think different.

Love this too -- I use this to document source code, being able to visualize a buffer or structure layout in the code is so nice!