Ask HN: What do you use for diagramming in software engineering?

A whiteboard and imagination from the oral documentation. It's actually something I'm working on getting my team to fix sense I got here. I'm interested in this topic.

It depends on the exact problem and how long term you need to documentation to exist. For a lot of things physically drawing out diagrams is great. It's fast to do and based upon the questions you get it's easy to draw more detail on the area being discussed.

For more long form docs I tend to use a mix of LaTeX's TiKZ (though I used to use PSTricks) for block diagrams and for a somewhat faster workflow I've used some of the diagramming tools which integrate nicely into an asciidoc based document. That can be graphviz, blockdiag, seqdiag, etc ( https://asciidoctor.org/docs/asciidoctor-diagram/ has a decent list of some of the options).

With any option it's easier to quickly sketch something out than it is to have some clear well organized diagrams which don't need any external context to understand.

Something long term, that you can use to onboard new employees. They can just look a the visual and reconstruct a mental map of how things are laid out at a high level, without this institutional knowledge having to be passed around verbally and subject to the quirks of human memory (and subject to individuals possessing this knowledge potentially leaving the team!)

Gliffy Diagrams and Draw.io are two that I'm using. Draw.io has a lot more features, export options, etc.

I use a combination of tools for visual documentation. Block diagrams and sequence diagrams together are a pretty effective means of communicating.

For block diagrams that illustrate relationships between components as a sort of directed graph, I prefer Omnigraffle (on OSX). It's fast and effective, easy to label boxes, lines, and interactions, and supports exports to pdf and png for quick sharing. Where omnigraffle falls over is in terms of its popularity and accessibility. You can't really review the diagram source as a part of the code review process, and the output diagrams are not useful to the visually impaired. Popularity is a factor because even if a dev knows some piece of block diagram software well, it's likely that they know a different one than anyone else. For that reason, we're not prescriptive about the tool used on our team, only that some form of block diagram is included with the documentation for a feature or component.

For sequence diagrams I use web sequence diagrams, for which I hold a commercial license. These diagrams are great for illustrating different workflows, with the caveat that we generally need several very similar diagrams to explain even the simplest features. These also benefit from having a straightforward text format that can be shared as a reviewable part of the source tree, and which can be read and edited by the visually impaired. Sequence diagrams are a more effective tool for demonstrating the veracity of code against a desired specification than block diagrams are, but understanding the top-level component layout is generally a prerequisite.

Not sure about the general popularity of either of these, but they've been an effective toolchain for me so far.