Besides that I sometimes still draw ERDs and I love JJG's Visual Vocabulary[1] for drawing "interaction diagrams".
What types of diagrams do you use with your team?
[1]: http://jjg.net/ia/visvocab [2]: https://news.ycombinator.com/item?id=26934577
Since I created a drawio integration extension for VS Code, I tend to create much more diagrams during coding, as they are really cheap to create. There is also an extension for IntelliJ and the diagrams work nicely in github readme files. After moving diagrams closer to code, I noticed that it is much easier to keep them in sync with the code base. Especially as PRs changing the code structure can include diagram changes at the same time.
I use them to model simplified class diagrams for documentation purposes, to model data flows, to create primitive mockups, to show the relationship between UI components (as embedded screenshots) and to show component dependencies. I try to follow UML, but I don't care about machine readability and prefer readability over UML compliance.
You can find some uses-cases of those diagrams here (https://dev.to/hediet/create-diagrams-in-vs-code-with-draw-i...).
I also get a bit of millage from time to time out of the Graphviz online demos. I use those to throw together graph-ish stuff on the fly.
It has now been renamed to diagrams.net: https://app.diagrams.net/
Github repo: https://github.com/jgraph/drawio
It's very easy to self-host, especially on Github Pages: https://github.com/jgraph/drawio#running
There's also desktop apps for Windows, GNU/Linux, Mac and Chrome OS: https://github.com/jgraph/drawio-desktop/releases/latest
The name draw.io seems to be everywhere in the code/documentation/community/stack overflow still and even searching for "draw io" shows "Draw.io - Diagrams.net" which just adds to the confusion.
Probably either names would have been fine, but at least be consistent about it.
The first is that the islands which should own the domain suffix, don’t, thanks to a wonderful piece of modern day British Imperialism. If you ever feel the need to donate to us, please give it to a more worthy cause.
Secondly, there was a security issue with the .io domain. In 2017, a researcher managed to take control of four of the seven authoritative name servers for the .io domain. We accept that mistakes can happen, strong processes limit the chances of them happening, but they still can.
However, the domain administrator made no attempt, at any time, to communicate with anyone about the issue. We’ve no evidence to suggest there is anything to be worried about, but the complete lack of communications means we have lost trust in whoever controls .io domains.”
Like draw.io, it is open source! (https://github.com/hediet/vscode-drawio)
* Use case https://plantuml.com/use-case-diagram
* Object https://plantuml.com/object-diagram
* Activity https://plantuml.com/activity-diagram-legacy
* State https://plantuml.com/state-diagram
Sequence and Activity are my most used - beyond the ones above logical architecture tends to be a Draw.io created abstraction that ends up in a Google Doc... stuff like this: https://camo.githubusercontent.com/f14ac82eda765733a5f2b5200... (not one of mine)
I don't care about the UML vocabulary, just give me boxes and arrows and labels and a way to draw them semantically instead of some overengineered point-and-grunt GUI.
Now, if anyone came up with a tool that checked that the code and diagrams match (no code generation please, the code is the source of truth!), now THAT would be lovely.
Just a CLI tool that can be run as part of a CI pipeline, which parses the code into an AST, and checks if entity A still has properties A.B and A.C, and methods A.D and A.E, and that A.D still contains a call to function F - and colors the arrows BRIGHT RED if there's a mismatch. That would be enough for committing a mental map of a codebase to documentation.
* Timing https://plantuml.com/timing-diagram - used it once or twice.
I mostly use PlantUML for myself, in lieu of drawing diagrams by hand (or pointing device).
My main use cases are a) when I'm toying with some higher-level design in my head and want to "see it" in picture form, and b) when making notes about the structure of code as I explore gnarly areas of a legacy codebase.
In that latter case, I've discovered that my "PlantUML notes" follow the code structure close enough that I should be able to coax my editor into generating these for me, semi-interactively. I might get around to doing that at some point.
Quite honestly, I'm surprised I haven't seen anyone doing a generalized "Language Server -> PlantUML" tool for asking questions about the codebase and getting responses in graphical form. As I mentioned yesterday[0], I find myself in need of being able to answer questions like "How does the code get from here to there?", and at least some language servers should have enough information to be able to give that answer[1].
That time when I spent a whole day building a sequence diagram by hand, to document how a certain subsystem is created and used in the very heart of the application, paid for itself very quickly - but I'd much prefer if it was a matter of couple minutes of tuning an invocation like:
querypuml --type=fromto --from=Foo.cpp:123 --to=Bar.cpp:456 \
--omit"::utils::*" --omit "SomeClass" \
--omit-files "module/irrelevant/*"
-o journey.puml
--
[0] - https://news.ycombinator.com/item?id=26937454
[1] - If a language server supports identifying function calls and "jump to definition" (xref), it already has a lazy graph of the code structure, so it's a matter of running a path finding algorithm on it. Of course this can never be perfect (see also: halting problem), but I think a minimum-effort solution would cover 80% of cases, and most of the rest could be covered if attached to a debugger that records traces.
Just my 100% subjective read.
But it's something to test out! :)
https://plantuml.com/preprocessing
It's enough to make it easy to organize common chart elements into libraries, and even create some DSL here and there - the latter being helpful if you're using PlantUML for note taking or in lieu of doodling :).
For instance, I got a very good mileage out of "trivial" definitions like:
!procedure call($source, $target, $call)
$source -> $target: $call
activate $target
!endprocedure
call("Someone", "SomeoneElse", "FooBar()")
asynccall("SomeoneElse", "SomeService", "Run(a=42)")
--
[0] - Which looks like a spawn of an unholy marriage between PHP and C preprocessor... but hey, it's a programming language.
Plantuml is excellent for some use cases, but not all.
They use kroki to enable embedded plantuml diagrams, you can save the whole thing as PDF than includes the source and can be edited in draw.io
* It's a lot of work to make them look right.
* They become outdated SO quickly. They're dangerously misleading as often as they're useful.
* Lots of people like to create diagrams, nobody likes to maintain.
Hand drawn dated diagrams have a sort of built in advantage that people will assume that it's not been kept up to date, especially if it's scruffy. Also they're quick.
I like the idea of generated diagrams better than drawn diagrams but unfortunately the software just isn't there yet.
Even when you can do it, they usually look shit because the program won't layout nearly (e.g. E/R) and you can't integrate changes to the source (e.g. tables) to annotations/tweaks.
It has a built in version control system: get a new piece of paper and keep the old one.
There is immense power in "reciting" the diagram in front of someone on a new piece of paper or whiteboard. It's essentially adding a whole new dimension to your diagram, as well as space for discussion and interaction along the way. I've not seen someone pull this off well in any electronic format.
Spending time refining diagrams is what you do when you're writing a thesis or book. You have to be very careful when designing your diagrams this way. But it's a complete waste of time when the diagram is for software under development. Those diagrams can and will become outdated very quickly.
But we have found that working together in real time -- making a diagram together -- is an incredibly efficient way to strategize about how to solve whatever problem at hand, and then come away with a shared understanding so we can work together on the execution.
We use Plectica[1]. Another popular one is Miro[2].
[1]: https://beta.plectica.com
[2]: https://miro.com
===
Usually, plantuml source is more readable, and it’s just almost like writing a list so it’s not too much work.
I like the idea of some sort of textual dsl that generates diagrams just not that one and ideally not a UML focused one.
But written lists are worthless to people who are illiterate
The main selling point for me was the "zoom in/out" aspect. Instead of having a HUGE UML diagram, you have a bunch of small diagrams, each focused on a single part of the described system and the interactions between its components.
But for level 3, 4 it gets tedious to do the diagrams at time and harder to keep them updated over time. Personally I prefer to just read the code and only have diagrams in special cases at this point
You can version your diagrams with your code (or in their own repo) using PlantUML, and by following the C4 Model you create digestible diagrams that are easy to understand.
In source, I generally use Mermaid[1] as its syntax is easily maintainable and understandable. And our documentation (mdBook) is written in markdown and can render Mermaid via a plugin[2].
When drawing quick diagrams during online communications, I use Excalidraw[3] as it's easy to use and has a nice whiteboard style to it. When I'm with my team (pre-covid), whiteboard or paper did the trick.
[1]: https://mermaid-js.github.io/ [2]: https://github.com/badboy/mdbook-mermaid [3]: https://excalidraw.com/
I shouldn’t have to re-adjust my mental model because of some stylistic/level-of-detail decisions by the author.
These diagrams would be interactive too.
Many systems are very similar in what they do. There are many times I am asking myself: “but how is this different from <well known architecture pattern>”.
Think about categories like append-only logs, search indexing, web requests, git trees, etc.
I’d love to be able to diff against two diagrams to the same problem and see how the approaches differ.
As a big fan of Domain Driven Design I found "domain storytelling" a useful technique when adapted to software systems.
With these diagrams it was much easier to convey complex systems and their temporal couplings. Especially to higher Management as they can actually "read" how the sequence of events flow.
Try it out and see if it can be another tool on your belt.
===
Swimlanes are basically process flow diagrams (aka flow charts) but with lanes that indicate which actor or system performs each process.
At my company, if an engineer gets tasked with a logically complex feature or a feature that involves multiple different systems, then we will often require them to use swimlanes to diagram out their new feature before they start coding it. The flow chart makes it easier for the business owner to double check the logic before it's implemented. The lanes help the engineer better understand more intuitive ways to organize their code (classes, methods, etc) and the interactions it will create. Without the lanes, code organization on logically complex features involving multiple actors can go off the rails pretty quickly.
For database table specs we use ERDs.
I hate Visio so much, I do not hate any other software that much.
It's a very flexible tool, and you can use it for just about any kind of diagram. The ability to use vector images to represent parts of the diagram is a real boon for certain types of diagram.
But it can be a real PITA to get things sized the way you want, positioned the way you want, text labels all aligned correctly etc. And if you have lots of layers of shapes, it can sometimes be really fiddly to select what you want.
In general, I much prefer to work with text-based diagrams - you're not nobbing about nudging pixels, but it also means diagrams are much smaller (disk space) and you get diffs.
-- EDIT --
Woah, I hadn't come across diagrams.mingrammer.com, and it looks amazing, exactly what I need for non-Visio network/infrastructure diagrams!
[1]: planttext.com/
I create architecture diagrams - these show how different components fit together, what network boundary they reside in etc. I like Visio for these in particular, because I can use different images to represent each component - I find it makes the diagrams easier to read.
I create "security diagrams", which are basically just a box for each significant component, with lines and arrows showing the direction of network communication and what protocol and port are used. These diagrams also show what kind of authentication is used.
I create use case diagrams, to show the actions that different roles within the system can perform.
I create very basic inheritance diagrams only to show different roles within the system.
I occasionally create action diagrams, if needed to help understand decision flows.
I occasionally create sequence diagrams, if needed to help understand the sequence of interactions between different components/modules/actors.
I very rarely create class diagrams - if I have to do this, it basically means the design is too complex (e.g. too much use of generics, too much use of inheritance etc).
UML is far from dead, it's just that people don't doggedly churn out and maintain every kind of UML diagram for every part of every system - they are really useful for explaining a few specific parts of systems.
I try to avoid over-use of inheritance, so class diagrams don't get used for that. Mostly I use unstructured boxes and arrows for entity-relations, and don't worry too much about notational rigour.
Sequence diagrams, to me, give the benefits of a flow chart, but with a much tighter explanation of the actual flow and relationships. You can read them from the upper left corner to the lower right, just like (western) writing. You get not just the entities involved, and not just the way they are connected, but the _ordering_ of those connections, which I find super helpful. The concept is simple enough that I can hand draw it on a whiteboard or scrap of paper, and for electronic formats, if you generate these from markdown you now have the same data in both a visual and textual format (handy for folks who have a harder time accessing pure visual presentations), and auto-generation from text makes it easy to update and so more likely to maintain as the system changes.
We also think Mermaid is a great project. I want to try the entity relationship diagrams next.
Component diagrams, what is connected to what?
Activity diagrams, what are the activities that happen, and have they got names?
Sequence diagrams, so microservices on top of microservices, hmm please show me how you get item x?
State Diagram, are you sure you have got all the possible state transitions?
ERD diagram, Chen style, I don't like it when the look like SQL tables (maybe we don't have/want/need a relational database, so lets not start shaping it like one at the concept stage). The physical/logical models I don't see much value diagramming.
BPMN can be useful alternative to Activity diagrams sometimes.
edit: left off Use Case diagram, so simple yet seen teams struggle so many times to articulate this.
A key thing about doing a diagram or document is that they force you to clarify your understanding. Another rule of thumb is if you are struggling to keep you docs/diagram in sync with your implementation, you have likely made you docs too detailed, its a high level map to guide not a detailed set of instructions on how to construct.
These are really good points. I've found that refreshing diagrams, even if's a hand drawn update, or modifications, to an older diagram for the new person on the team can be valuable in identifying what is different and getting a sense for how important it may be to redocument (or even refactor) that system.
Simply putting dates on diagrams so people aren't guessing is helpful. It goes with doing something like automatic labeling of content in your wiki that's over a certain age so that people are mindful.
And everyone understands them without any help or explanation.
My university took part in its research (less nowadays) and I’m really glad I had the chance to learn it. I still use it at work.
For other uses - yeah, ERD and sequence diagrams are the workhorses.
When that's not sufficient, usually a sequence diagram adds a whole ton of clarity
For reviews with new people, a limited ERD is handy, mostly to show where the 1:n or n:n relationships are
I somewhat frequently write truth tables to get a good breakdown of different usecases
I use web sequence diagrams for my sequence diagrams, but mostly everything else I'm drawing by hand in paint 3d with the surface's nice pen drawing
The major problem I see in UML is it tried to unify things, but in reality, we use diagrams for different purposes and different audiences. The same idea could be found in C4.
I don't strictly follow C4, instead, I choose notions I find suitable for the audience and context (eg: architecture for tech people, domain modeling for domain experts, or just abstract ones help myself thinking)
Also, ER diagrams because it's easy to translate drawing to normal form
When I create diagrams I prefer typing than drag-and-dropping and gleek.io is pretty fast.
You can check the diagram examples:
* Basic shapes https://app.gleek.io/diagrams/basic
* ERD crows foot https://app.gleek.io/diagrams/erdiagram
* UML class diagrams https://app.gleek.io/diagrams/class
* UML sequence diagrams https://app.gleek.io/diagrams/sequence
Recently we made also video tutorials, hopefully it helps when you are learning to work with a tool:
https://www.youtube.com/channel/UCMl_1_jjnhgPAsRBuJ0yzAA
Feel free to ask anything, happy to help!
1. System architecture 2. Flowcharts
NOTE: I don't try to mix the two. Architecture diagrams are the what, not the how. I find a lot of people try to mix them.
Beyond this, sequence diagrams are useful.
I use these for explanatory documentation, mostly. Like, we have a "architecture guide" for each service we maintain, that usually contains a system architecture diagram, and maybe a flowchart of the "happy path" processing. But these are simplified versions things... like, I usually leave configuration details, like networking and access control out of the architecture guide, and just focus on "what services are interacting with each other directly".
Also, LucidChart has an "AWS import" method, that actually works well, but can be a little like drinking from the firehose. It's a solid tool, but mostly as it's own kind of reference document, like, API documentation for your AWS stuff.
From a theory-focused POV, flowcharts are supposed to be essentially complementary to dataflow diagrams. But the latter are often more useful for practical concerns.
For example, the decision nodes will be somewhat vague, e.g., "Does event have good location data?" The details of that question are actually very complex, covering multiple fields from different data sources. But the gist is very much "if we don't know it, we're going to then hit this location subsystem". This is in a processing chain that's pretty complex, so, it's just kind of a basic guide.
Most of the consumers of these docs are often engineering managers who want a picture of the system, but aren't performing real engineering analysis.
I don't use them for detailed technical analysis. Usually, that just involves code.
I find dataflow diagrams can be useful, but even those can be overwhelming, depending upon the audience.
Ultimately, I don't think you can just talk about diagramming without the context in which you're using the diagrams. I rarely use diagrams with technical reference documentation these days. I use them with high level explanations or tutorials.
But before the formal idea is developed I just sketch in whatever diagram grammar seems most appropriate for the problem.
We don't really use diagrams for formal communication. Most formal discussions are around concrete schemas and API:s.
* ERDs
* UMLs sequence diagram
* State diagrams
* JJG's VisVocab (for diagramming interaction, i.e.: screens and actions): http://jjg.net/ia/visvocab
* And some (not well defined) type of architecture diagrams
* Sometimes a branching diagram to explain a hairy git branching issue to a co-worker
PlantUML works best with sequence diagrams because automatic layout is much easier ("sequential") for them.
In documentation I typically use a mix of ditaa[1], mermaid[2], and graphviz[3]. I used ditaa for architecture diagrams, a mix of sequence, flow chart, and ER diagrams in mermaid to explain protocols or interactions; and I use graphviz usually for datastructures or dependencies, etc.
[1] https://ditaa.sourceforge.net
For anything UML-related, Enterprise Architect is quite good, but boy you better know UML. That ain't user-friendly in the least. But super powerful and there are a few more like that out there with somewhat limited free versions.
Long story short, my best choice is yEd. And I still reach out to Powerpoint every now and then.
I don't strive to be 100% compliant with a given methodology, I see those as diminishing returns. Class, sequence, architecture, a bunch of lines and boxes, whatever does the job.
It depends on your audience & message!
And excalidraw: https://excalidraw.com/
I can’t remember what program we used. But now we are on Postgres and we talk about creating a database diagram again since we found it so useful. We just haven’t found a good program yet.
Otherwise nothing much... random visio-ish things made in draw.io or sometimes scribbled out on the fly during presentations using a wacom tablet. I tend to prefer words, code snippets and config to explain my stuff these days.
I used it to write this document with two diagrams: https://loan-free-ed.neocities.org
Other tool I like are PlanetUML[1], BoUML[2] and Modellio[3](it is very heavy though on system resources!)
[0] https://casual-effects.com/markdeep
[2] https://bouml.fr
Also truth tables if I have to work with booleans in excel.
Otherwise I do a lot of off-the-cuff statemachine and sequence diagrams, I guess you would call them. Very often literally scrawled on a napkin and then photographed with my phone.
I recently stumbled upon code to diagrams tools like app2code and plantuml. I really enjoy this because I can focus on the model and not the aesthetics. Also making revisions to code is a lot easier than fiddling around with draw.io.
Does any one have any tools like this they can recommend?
Structural diagrams: do not "solve" anything really. (I know, they might be good for docs...)
Also recently I started to think in terms of events. Look up FRP, "real OOP" and Cycle.js.
For these, there is no standard diagram yet, so I am came up with my own - still under change.
For that, I started to use Lucidchart, because its available on mobile/tablet as well in browser as desktop view and it gives full functionality.
It's also really nice & snappy.
"IFML provides ... tools for the definition of Interaction Flow Models that describe the principal dimensions of an application front-end."
Just a few days ago there was a thread about the death of UML... like anything from omg.org, I suspect there's a useful subset to carve out that could be useful to model applications.
So I make all kinds of diagrams, mostly as demonstrations. When developing a library itself, especially one where there are phases (Graph Objects must measure themselves and their parts, and draw in a certain order, and not more than they need to), state machine-style and flowchart-style diagrams are awfully helpful.
I'll use draw.io usually but if it's to clarify something small, I'll just draw it on my notebook and snap a photo of it.
That's what I love about the activity diagram. Communicates a ton of information in a form that even if you've never seen it, it will be pretty intuitive. And creating it is also super lightweight.
I draw them with Plantuml. Text input is really a must have for me. On crowded diagrams it may be difficult to fine-tune the layout though.
I still sometimes do class diagrams, although I do not find they carry much info compared to the code. The meaning of arrows is ambiguous and they're too verbose. APIs are better documented with e.g. Doxygen.
UML seq. charts to develop the SDL state diagrams.
Object Role Modelling for database schema design (https://en.wikipedia.org/wiki/Object-role_modeling)
we also do produce some reverse engineered code map with doxygen here and there, so we can cut down cross dependencies and dependency cycles as the codebase matures
So much so that thanks to https://bramp.github.io/js-sequence-diagrams/ I've got a Netlify-powered static site for creating them interactively at https://sequence-diagrams.netlify.app/ using their JavaScript library.
I'm not using it as a UML tool strictly, but being able to document everything, generate the document in HTML and being able to store it alongside design documents help me a lot.
Small algorithms are hand drawn first, and documented extensively in code. If they're crucial for the research I'm doing, I carry them to the same StarUML document too.
Apart from this, sometime I also use "sequence diagrams" - vertical lines representing systems/modules to illustrate the sequence of flow of any system/user action.
It has been used for everything from SQL design to quest scripting in games.
I don't use it anymore because I made my own JSON database: http://root.rupy.se
Sequence diagrams in PlantUML (using the awesome VScode extension)
Because I just want some shapes, lines and clip-art to communicate an idea clearly, quickly, and informally.
I remember the UML days and their endless variety of turgid tools, don't want to re-live those experiences.
UML is pretty much dead, so 'standard' diagrams are not worth the effort unless contractually requested.
I used to use Yed, but now I like drawio.
I really like it simplicity in creating charts
Common sentiment, I suspect.
- Sequence Diagrams
- State Diagrams
- Activity Diagrams
I use PlantUML to render all these, with the added benefit of being able to produce it programatically.
I should write a book on it, maybe give seminars and sell training materials.