Inkscape Cloud Architect
github.com
github.com
If/when I make the jump to actual documentation I use Mermaid so I can keep everything tidy under source control.
In general, if sketching it out, whether alone or with multiple people, using something simple I can click, drag & label is more than enough and helps me keep the flow. (I would stick to actually drawing - either on a whiteboard or something digital - but my handwriting is absolutely atrocious)
As soon as I'm done sketching and move over to actually documenting a concrete solution, something code-based like Mermaid - as you said - is much nicer. But both are entirely different processes for me.
The Excalidraw export format is JSON, so you might use that in source control just as well. Or include the format in PNG or SVG export (which draw.io supports also).
Also this plugin works fine in github.dev so it's like a better version of draw.io official site.
Recently discussed on HN
Imo Inkscape is far more powerful then draw.io. it's also faster.
In contrast to, for example, proper modeling tools like Sparx Enterprise Architect or Visual Paradigm.
It doesn’t really matter then if you’re using an online tool or a native one.
This lets you produce diagrams with code.
- Can check the textual description of the diagram into version control and track how it changes over time
- Can easily diff 2 versions of the same diagram
- Adding elements to a large existing diagram using WYSIWYG tools can be tricky (eg: you may have to move or reroute existing elements to make enough space)
Another cool idea is to create multiperspective diagrams with different views for different purposes (eg: code structure, deployment, network architecture, security):
- Clarity. By breaking up diagrams into perspectives, diagram authors can bring much more clarity to a system. Individual concerns can be spread out over many perspectives, allowing each the space it needs without interfering with others.
- Extensibility. Multiperspective diagrams share a model, so creating additional perspectives from an existing diagram is incredibly easy, far easier than starting from scratch each time.
- Maintainability. A corollary to the above, individual perspectives can be modified without affecting the others. Diagrams that are easy to maintain get maintained, while diagrams that aren’t fall out of date quickly. Multiperspective diagrams greatly help in the fight to keep documentation up-to-date.
This is a cool demo: https://app.ilograph.com/demo.ilograph.Stack%2520Overflow%25...
For other textual diagramming tools and ideas, please see this thread: https://news.ycombinator.com/item?id=37222855
Disclaimer: I'm not affiliated with Ilograph, just stumbled onto their blog and I think they have a lot of cool ideas.
The 'what does this element do for my system' is vastly more important than the 'which in vogue offering from my cloud provider implements it'.
I highly suggest folks take a look at the C4 Model: https://c4model.com/
That's the problem I have with the `diagrams` Python package (https://pypi.org/project/diagrams/), I find it extremely useful, but the "Generic" section doesn't even include a "Queue" component, and the "OnPrem" section only includes specific queue products.
That Python package is exactly how I like to create diagrams, so I keep using it, but I always have to add my own badly-designed custom icons to it, which look so bad that I wouldn't dare send a PR to add them upstream.
You don't have to stick to their software either, use DrawIO if that's what you prefer, but understand the main concepts that C4 is trying to impart about the separation, what goes on the arrows, and how useless icons can be.
Precisely. Any time someone utters the descriptor "best practice", at best, you do yourself a favor by examining it with a critical eye and judge whether it is a good practice to follow (and a good fit for your project) or not. At worst, you beat back the consultants framing it as "the one and only way to do things (with the implication that everything else is wrong)."
But yes, this is fundamentally an OOP thing, and especially the component layer is very much just fantasy. In no real OOP software do these meat reusable components not have super strong binding to each other. Yeah you may have the SignIn controller and the ResetPassword controller both talking to the SecurityComponent, but in the end that's guaranteed to be implemented in such a way that you cant use any of them without all the others connected, and its likely that testing this means writing a mock for each of them that is so complex it may as well have its own tests.
They are thinking of their problem, and building their solution entirely out of blocks made from the words that make up the problem. "We need users to be able to sign in and reset their password" becomes SignIn component and ResetPassword component, when really this is just a matter of changing a hash and possibly some encryption keys, and could just be a handful of validate(), reset() et al functions on the security module.
Your comment is useless to me; so ultimately I'm not likely to give it any credence.
Whats your background that you have simpler alternatives?
You could also actively ignore this for half a decade and see if the tides are changing again. I can almost taste a push towards "lower amounts of abstraction levels and system boundaries lead to smaller stack traces which have xyz advantages" on the horizon. Hang in there, solve the problems you have.
Either way, it’s a genius name.
Not everything needs that level of design though. Just because architects do detailed FEM analyses for skyscraper design doesn't mean your garden shed needs the same level of attention.
If an application continues to grow, and the team building it grows, it will eventually need to be broken apart into smaller independent blocks to make it practical for a large team to work on it and maintain it. In a smaller codebase with fewer engineers, you can make different choices.
A lot of these components are strongly linked, and will hold mutable references to each other, which is often pretty terrible.
In procedural code world, everything is connected to each other, but not strongly, and there are very few mutable references.
You may just have a solid codebase.
Great tooling strongly based on C4, I use it a lot.
In companies/organizations that are large enough you always get a certain amount of project bureaucracy, ass coverage, and other documentation that doesn't technically do anything more than impress easily impressible types. But it's rarely actually useful. I usually just go straight to the code repositories and ignore things like wikis and other crap. Complete waste of time usually. Show me what you really have. I'll figure it out in no time.
Two mistakes people make with these tools:
1. Spending lots of time using them believing that the output is actually useful/valuable to engineers. Your time is more valuable. You should be doing more productive things. Minimize time you spend on drawing pretty pictures. They didn't hire you for your graphical design skills. This is of course subjective and context dependent. Sometimes it's just required to have diagrams. E.g. operations people like having good documentation just as a way to ensure that they can follow strict processes and make good decisions as to what is in their scope and what needs escalating. There's also a certain amount of impressing the customer, senior management, or other stake holders that "we have stuff". The bigger the company, the bigger the need for project bureaucracy like this. But it is bureaucracy and you want to be efficient with it. Quick and easy.
2. Believing that these are design tools. They are not. They are documentation tools. You use them after you build the thing. Before you build the thing, you use something like a white board. Or pen and paper. A napkin. Anything fast and easy that doesn't slow you down. It's transient stuff and when you start building the thing you'll realize half a dozen topics you did not take into account. So, other than as a record of all the design mistakes you are making, such diagrams have no long term value. You document the solution after you found, solved, implemented, and tested all the design problems. Not before.
Friendly reminder that the places where you are least likely to find diagrams:
- Any kind of large open source project. Or any open source project really. Just not a thing. The bigger and more complicated they are, the less likely it is to have diagrams. Reason: they are redundant and absolutely nobody volunteers to sit down and do them. Just ask yourself: "what would Linus Torvalds say when asked to provide diagrams for the linux kernel". I imagine a fair bit of cursing would happen.
- Especially open source projects that are about producing diagram tools. I personally find this highly ironic. People won't eat their own dog food when the dog food is diagramming tools. Diagramming tools are something you build for others to use. Go look for it on Github if you don't believe it. All you will find is toy examples but nothing actually documenting these tools in any level of detail.
- Small startups or other companies that are highly innovative and have a fast pace of change happening all the time. Reason: people have better things to do than mess around with diagrams. The rainy afternoon where you really have nothing more valuable than messing around with boxes and arrows to do never really happen.
Where do you find people messing around with diagrams? Bloated engineering teams in corporate situations. The more boring the company, the more useless types they employ, the more diagrams you will find. People insisting to each other that "somebody" (not them) should do a diagram. I usually just bounce the question when it comes up. "Great idea, when can you have it done?" Usually the implied suggestion is that I should sit down and waste my time doing a diagram for them that they will never even look at for more than a few seconds. It's write only documentation.
https://www.unravelled.dev/how-architecture-diagrams-enable-...
I've been in plenty of companies with diagrams and universally they were incomplete, not that informative or helpful, typically outdated, and kind of obvious. That's because they are typically rush jobs exactly because the best people that could be doing these diagrams have way more important/urgent/valuable things to do.
I just had a call about the nuances of high volume email and I was like so are we going to talk about the details or ?
And he interrupted any time I would give details specific to PMTA config and architecture so he could show his useless diagram that just had
[MTA]
Then the owner on the call would hear parts of what I said and would say ooo can you diagram that
I just shook my head, and this went on for 1+ hours
It cuts your effective dynamic range in half, but works pretty well. And adjusting opacity is actually somewhat easier than adjusting color hex values
I haven't tried it with colors though - but I expect it'd work as well
In contrast, forcing a white background on people running dark mode is kinda ugly in my opinion as you end up with a border/cutout and it doesn't flow with the rest of the content as well
But even if it's ugly (https://imgur.com/a/bsLu54F), I prefer that than the alternative (https://imgur.com/a/ccuJq36)
It has diagram standards + icon sets for top cloud/compute platforms.
Plus, if you use VSCode, there's a solid extension you can use to create and include the diagrams in your project.
Could not programaticly import/update schema without tons of additional mousing around.
Auto rearrange could not handle large schema.
I'm slightly disappointed.
React Flow [0] until now is the component that's closest to this. Others, Excalidraw [1] and Tldraw [2] may be integrated to support this, with some additional effort.