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...).
* 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)
* 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.
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 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.
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.
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.
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.
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.