Design structured diagrams, built to increase your team's trust in your docs(icepanel.io)
icepanel.io
Design structured diagrams, built to increase your team's trust in your docs
https://icepanel.io/
82 comments
What do you think of this one?
I tend to use .drawio.png extension and then collaborate inside the repo in real-time using vscode live share (https://visualstudio.microsoft.com/services/live-share/) and the drawio extension together (https://marketplace.visualstudio.com/items?itemName=hediet.v...)
Then, in markdown/readmes use .
It will render locally, and in GitHub, and also if you use remark or something like that, it will still render as an image.
Then, in markdown/readmes use .
It will render locally, and in GitHub, and also if you use remark or something like that, it will still render as an image.
Author of the drawio extension here, nice to see you using it!
I can highly recommend using the *.drawio.svg extension though! Svgs also work in Github readmes and perform much better overall. They also work much better over liveshare!
I can highly recommend using the *.drawio.svg extension though! Svgs also work in Github readmes and perform much better overall. They also work much better over liveshare!
Thank you for your work. Best extension ever.
Wow, thanks for the tip!
Love the extension, great work
Love the extension, great work
Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.
How do people not know how to get or use draw.io? You literally go to draw.io and can use it online.
We're replaced our diagramming with it instead of things like omnigraffle as it means everyone has access to tweak the diagrams without having to buy software (and then buy upgrades and plugins), and by embedding the diagram in the .png there's just one file to keep track of.
We're replaced our diagramming with it instead of things like omnigraffle as it means everyone has access to tweak the diagrams without having to buy software (and then buy upgrades and plugins), and by embedding the diagram in the .png there's just one file to keep track of.
I've worked at places where people have exported draw.io as PNG/PDF on internal wikis for diagrams. But what happens when you want to change it? You then have to track down the people who made them, and get access yourself - or find it buried on someone's google drive.
With PlantUML you usually commit your diagram's text syntax to VCS, often close to the code.
As far as usability, we're never going to agree. I find it tedious, compared to writing predictable declarative syntax.
With PlantUML you usually commit your diagram's text syntax to VCS, often close to the code.
As far as usability, we're never going to agree. I find it tedious, compared to writing predictable declarative syntax.
drawio embeds the code in the png, so you just edit it in situ.
Wait, drawio embeds the source and rendered version in the same file? That's great!
Here's more info => https://joe.blog.freemansoft.com/2020/10/diagram-definition-...
Here's more info => https://joe.blog.freemansoft.com/2020/10/diagram-definition-...
You can also use it offline, there's a downloadable Electron app they provide (AppImage on Linux).
The shapes libraries are pretty nifty and extensive (just need to turn them on).
The shapes libraries are pretty nifty and extensive (just need to turn them on).
Wow, this is interesting. Are there any diagramming tools that allow importing PlantUML to display them a little nicer than the examples?
There’s some nicer looking ones here:
https://crashedmind.github.io/PlantUMLHitchhikersGuide/
https://crashedmind.github.io/PlantUMLHitchhikersGuide/
> I’ll never use a proprietary tool that doesn’t have declarative syntax
Can you provide an example of what you're referring to?
Can you provide an example of what you're referring to?
PlantUML diagrams are generated from plain text, they can easily be embedded in markdown or even in code (I'm sure there's a plug-in for that!)
Plenty of examples here.
https://plantuml.com/state-diagram
Plenty of examples here.
https://plantuml.com/state-diagram
And importantly, because they're text, they can live in a version-controlled environment. I mainly use them within Confluence, and even there you can diff between versions to see changes.
I've always felt that these type of tools shouldn't have a traditional home page with sign up, sign in, etc. If you go to Excalidraw's website, it immediately launches the application for you to start using it. If you need extra features, only then you go to a page that provides details, pricing, etc. This is a beautiful pattern that makes these type of tools a daily habit for people to use. I don't want to create an account to try the app or use it in its most basic form.
I get that, but they want to collect your email to improve marketing. If the product is strong enough it may not matter. Practically speaking, I think getting user signup info is pretty important.
The thing is, we all know they want our email address so they can market to us, so there’s absolutely zero chance of me ever entering a real email address into that box.
Pop up a modal after they've been using it for a while. Don't shove it in my face the first time I visit.
I don't get it. Do marketing mails ever sell anything? Or changing the name of the company or any of those other transparent manipulations? It's insulting.
The product should wow the user and sell itself and then the user will come asking to pay for more features. I've bought many products this way.
There's no way I'm signing up for these things.
The product should wow the user and sell itself and then the user will come asking to pay for more features. I've bought many products this way.
There's no way I'm signing up for these things.
I usually use Visio for diagrams like this. It's a very powerful tool, but it's expensive, and really fiddly to use such that everything is aligned and sized the way I want - I invariably spend far too long adjusting size and position.
Something like this could be really useful, and I'm keen to give it a try!
If the founder is here, a question: what formats can you export diagrams in? My biggest fears in using something like this would be lock-in, or it shutting down and losing everything.
Something like this could be really useful, and I'm keen to give it a try!
If the founder is here, a question: what formats can you export diagrams in? My biggest fears in using something like this would be lock-in, or it shutting down and losing everything.
Hey Gordon,
It'd be great to hear your thoughts/feedback on the tool. Please feel free to reach out to us.
In terms your comment about lock-in I understand your fear and I think a lot of companies will share this. We currently offer PDF/PNG export however due to the interactive nature of our diagrams we're looking into how we can provide an interactive export. An IcePanel file is also an idea we're looking into. We'd love to work with you if you have any specific ideas in this area.
It'd be great to hear your thoughts/feedback on the tool. Please feel free to reach out to us.
In terms your comment about lock-in I understand your fear and I think a lot of companies will share this. We currently offer PDF/PNG export however due to the interactive nature of our diagrams we're looking into how we can provide an interactive export. An IcePanel file is also an idea we're looking into. We'd love to work with you if you have any specific ideas in this area.
A native app would also allow you to access different market segments. E.g., I work with a fair amount of DOD-controlled information, and storing it in a cloud is not an option. I'd be all over an app like this that allowed us to use local storage.
Have a look at diagrams.net, you can run it locally, and there are quite a few interactive elements (panels you can close and this kind of stuff).
Having used Visio and Diagrams.net, Visio really is the least productive one. Constantly fighting with the unpleasantness of applying little tweaks made it my 3rd choice. 1) Diagrams.net 2) PlantUML 3) Visio
What size of company and what industry do you work in out of interest?
I work as an architect for a consulting and off-shoring megacorp. I mainly work for European clients in the oil and gas sector, but recently have worked in finance too. I find Visio (or any visual diagram tool) useful for hacking together a diagram collaboratively.
I also have a side business (me and a co-founder), and I'm planning on making the plunge and going full-time on it in the next few months - there too I've used Visio, because it's what I'm used to, and I get a license with our Microsoft Action Pack subscription. Here though, I'd probably prefer to move to a declarative model, like PlantUML (I only recently found out it works with icon sets, so can do things like nice architecture diagrams too).
I also have a side business (me and a co-founder), and I'm planning on making the plunge and going full-time on it in the next few months - there too I've used Visio, because it's what I'm used to, and I get a license with our Microsoft Action Pack subscription. Here though, I'd probably prefer to move to a declarative model, like PlantUML (I only recently found out it works with icon sets, so can do things like nice architecture diagrams too).
I'd love to be able to export to a vector format - something I can load into another diagram tool. Not sure of the Visio format is open and documented, but being able to export to Visio would set my mind completely at ease.
Aside from that, I'd echo what a couple of others here have said about having a desktop app version, which would work with local, rather than cloud storage - I generally prefer to have full control over my data and how it is managed. I personally wouldn't mind an Electron app (presumably a native app is going to be a lot of work).
I look forward to trying it!
Aside from that, I'd echo what a couple of others here have said about having a desktop app version, which would work with local, rather than cloud storage - I generally prefer to have full control over my data and how it is managed. I personally wouldn't mind an Electron app (presumably a native app is going to be a lot of work).
I look forward to trying it!
The visio format is basically zipped xml, and its extensively documented by Microsoft.
I was considering Visio until I saw the price, the only alternative I found was MyDraw[1], which looks competent and is much cheaper ($69). I haven't used it yet though. In the past I've relied on Dia[2].
[1] https://www.mydraw.com/ [2] http://dia-installer.de/
[1] https://www.mydraw.com/ [2] http://dia-installer.de/
Huh - if you work in this domain - how is Visio very expensive? It's a few hundred dollars for things that save you tens and hundreds of work. It also has an unbelievably rich extensibility model - almost too complex.
The bigger issue is a) it doesn't do many of the things that we as architecture and design work requires - declarative rules (Component A --> connects to --> Component B) - enforce this rule without my having to worry about arrow drawing b) Version management c) Visio's default of a printed page as Canvas is incredibly cumbersome - we want big canvases in which we can zoom in / out liberally for large diagrams (hundreds of components).
It's more a question that it's not really an architecture tool for large systems. It's a general purpose tool that we've attempted to manipulate. So it doesn't work well for in-depth uses.
The bigger issue is a) it doesn't do many of the things that we as architecture and design work requires - declarative rules (Component A --> connects to --> Component B) - enforce this rule without my having to worry about arrow drawing b) Version management c) Visio's default of a printed page as Canvas is incredibly cumbersome - we want big canvases in which we can zoom in / out liberally for large diagrams (hundreds of components).
It's more a question that it's not really an architecture tool for large systems. It's a general purpose tool that we've attempted to manipulate. So it doesn't work well for in-depth uses.
> if you work in this domain - how is Visio very expensive?
Working for a megacorp doesn't mean they shower their people with money for tooling (or anything beneficial, actually). They are incredibly wasteful in some respects, but very seldom in ways that benefit the people working for them, or the work they do for them. In truth, they are a bunch of c*nts that couldn't care less about their people ¯\_(ツ)_/¯
But now I digress, and will get back on topic :P
Also, when I mentioned cost, I meant in general - not just specifically for me in my specific day job. If you're solo-bootstrapping a startup for example, $280-530 might seem relatively expensive for a tool that you will seldom use. Perhaps less of an issue if you're using O365, or the Microsoft Action makes sense for you.
> Visio's default of a printed page as Canvas is incredibly cumbersome - we want big canvases in which we can zoom in / out liberally for large diagrams (hundreds of components).
I don't understand your argument here; the Visio canvas can be whatever size you want - you can even let it auto-expand as needed if you want. I regularly do use it for diagrams of large systems with numerous components, and can zoom in/out just fine.
> It's more a question that it's not really an architecture tool for large systems
I like declarative diagrams very much (versioning is a huge plus too), and have been making much more use of them recently, mainly for UML diagrams. But actually, for large architectural diagrams they can become a sea of text that's difficult to work with. Being able to visualise* things more intuitively can be a bonus.
> It's a general purpose tool
This is one of the things I like about it - I can do architectural diagrams, sequence diagrams (or any kind of UML diagram), process flows, swim lanes, anything really.
Still, it has a gazillion features and capabilities that I'll never use (such as the extensibility you mention), and it can be really fiddly to size and position things just-so. Hence, I think something a little more focussed (like the OP's app, or the likes of draw.io) could be a great alternative.
Working for a megacorp doesn't mean they shower their people with money for tooling (or anything beneficial, actually). They are incredibly wasteful in some respects, but very seldom in ways that benefit the people working for them, or the work they do for them. In truth, they are a bunch of c*nts that couldn't care less about their people ¯\_(ツ)_/¯
But now I digress, and will get back on topic :P
Also, when I mentioned cost, I meant in general - not just specifically for me in my specific day job. If you're solo-bootstrapping a startup for example, $280-530 might seem relatively expensive for a tool that you will seldom use. Perhaps less of an issue if you're using O365, or the Microsoft Action makes sense for you.
> Visio's default of a printed page as Canvas is incredibly cumbersome - we want big canvases in which we can zoom in / out liberally for large diagrams (hundreds of components).
I don't understand your argument here; the Visio canvas can be whatever size you want - you can even let it auto-expand as needed if you want. I regularly do use it for diagrams of large systems with numerous components, and can zoom in/out just fine.
> It's more a question that it's not really an architecture tool for large systems
I like declarative diagrams very much (versioning is a huge plus too), and have been making much more use of them recently, mainly for UML diagrams. But actually, for large architectural diagrams they can become a sea of text that's difficult to work with. Being able to visualise* things more intuitively can be a bonus.
> It's a general purpose tool
This is one of the things I like about it - I can do architectural diagrams, sequence diagrams (or any kind of UML diagram), process flows, swim lanes, anything really.
Still, it has a gazillion features and capabilities that I'll never use (such as the extensibility you mention), and it can be really fiddly to size and position things just-so. Hence, I think something a little more focussed (like the OP's app, or the likes of draw.io) could be a great alternative.
A question I always have for diagramming software is how it handles refactoring. This is often the most frustrating part of every tool. How does IcePanel improve this experience? Group selection and dragging to hopefully have enough room for something new is not workable in complex diagrams.
For diagrams that are long-lived and refactorable, diagrams-as-code is really your only option. Changing complex diagrams with drag-and-drop interfaces is a nightmare.
I wish there would be a mixture of diagrams.net and mermaid.
draw.io/diagrams.net has a mermaid plugin
https://github.com/nopeslide/drawio_mermaid_plugin
https://github.com/nopeslide/drawio_mermaid_plugin
Fantastic, thanks.
We want to help users spread complexity across several diagrams with the aim of reducing enormous diagrams that cause confusion.
IcePanel allows you to quickly create tabs for each diagram you want to communicate and a model view to keep all the properties in sync.
We're also looking at how we can bring our diagrams into source control to allow it to be maintained easier.
We're also looking at how we can bring our diagrams into source control to allow it to be maintained easier.
[deleted]
If a diagram is too complex, shouldn't you just add more abstractions? That would simplify the refactoring too.
I have been using whimsical for diagrams and prototyping prototypes. Some of my colleagues are converted after they have seen it. The ease of use is the best I have seen so far. It is bold and easy to read.
Seeing the demo page, I have to ask: why do we stay with the traditional black, grey and white colors for diagrams?
Seeing the demo page, I have to ask: why do we stay with the traditional black, grey and white colors for diagrams?
i love the ease, but i wish they had better support for importing/exporting from/to other tools like drawio and plantuml.
What on earth do diagrams have to do with trust in docs? Docs that are useful, accurate, and up to date would increase trust.
We agree - useful, accurate, and up to date docs are what increases trust! We're bringing docs closer to the diagrams to visually explain your system in smaller chunks. We've found docs often accompany diagrams, and they become out of date as soon as they're exported! We think instead of diagrams being in docs, docs should be in the diagram.
Alternatively, they can live together.
For example, I ended up writing this to integrate diagrams and Sphinx. https://github.com/j-martin/sphinx-diagrams
Similarly there's https://pypi.org/project/sphinxcontrib-plantuml/ and https://mermaid-js.github.io/mermaid/#/ (among other similar tools).
For example, I ended up writing this to integrate diagrams and Sphinx. https://github.com/j-martin/sphinx-diagrams
Similarly there's https://pypi.org/project/sphinxcontrib-plantuml/ and https://mermaid-js.github.io/mermaid/#/ (among other similar tools).
Eventually your docs will be updated and noone will be around to update the included diagrams. And when the users (the developers!) notice the discrepancy, trust will decrease.
We use http://diagrams.mingrammer.com in our team. Diagrams from python code.
Nice, I’m pretty excited to try this out for my personal projects. Been looking for something like lucidcharts but meant for code architectures.
I am searching for quite sometime an application which can detect, and convert hand drawn shapes on a computer (using mouse or stylus) to proper shapes. This will make life so much easier for someone who makes architecture diagrams frequently. The closest offering I could find was with iPad 'Shape Recognition'[1]. But the number of shapes it detects is limited. It also does not appear to be really - meant for or integrated with - tools like draw.io.
[1] https://www.apple.com/ipados/ipados-14/features/
[1] https://www.apple.com/ipados/ipados-14/features/
"Error: could not handle the request" looks like HN hug of death did its job.
I've had really bad experiences trying to serve web workloads from lambda or cloud functions type services. The ramp up period to scale for a sudden influx of traffic is ridiculously slow. basically it can't handle a thundering herd at all unless you pre-provision enough concurrency which is incredibly expensive.
I'm sure these kinds of services have good use cases for back office async tasks and things like that, but for web workloads it doesn't really work.
I'm sure these kinds of services have good use cases for back office async tasks and things like that, but for web workloads it doesn't really work.
We're only using cloud functions for the initial redirect for some links, looks like we're hitting some kind of quota limit in our cloud environment. Should be fixed now.
Try this? http://icepanel.io/
Is anyone using dot and/or graphviz in earnest for something like this?
I’ve tried playing with graphviz and dot for some system architecture diagrams - mostly because it integrates well into our internal MediaWiki site and, it’s … ok I guess.
I’ve found it pretty easy to rapidly throw together some reasonable diagrams with relatively little effort but where it really seems to fall down is with the layouts themselves. I’ve found that just so hard to get things to lay out how I want them to and the syntax for this seems particularly arcane to master. I usually just give up after a while and end up with a layout I hate but that at least conveys the information I want to convey.
I’m probably making things hard upon myself because I manually crank out the markup by hand and brute force slog through it until it looks ok. Reading through this thread made me realize that I could potentially be using PlantUML or something similar to make this less awful.
I’ve found it pretty easy to rapidly throw together some reasonable diagrams with relatively little effort but where it really seems to fall down is with the layouts themselves. I’ve found that just so hard to get things to lay out how I want them to and the syntax for this seems particularly arcane to master. I usually just give up after a while and end up with a layout I hate but that at least conveys the information I want to convey.
I’m probably making things hard upon myself because I manually crank out the markup by hand and brute force slog through it until it looks ok. Reading through this thread made me realize that I could potentially be using PlantUML or something similar to make this less awful.
PlantUML uses a declarative approach to diagrams and works well with dot and graphviz.
What tools like these need is monitoring capacity. Hook your diagrams to your logs and health status, and then you have a compelling reason to actually keep them up to date.
Yeah I was thinking something like this too, hopefully someone makes this if it hasn't been already.
If the diagrams had some linkage to your code you'd be able to see what a failed unit test means in the overall context of the app, what code is used in which block, what protocol is used for connections between blocks, a summary of what each block does etc...
A monitoring tool as you say - and since you'll use it often you'll probably keep it up to date
If the diagrams had some linkage to your code you'd be able to see what a failed unit test means in the overall context of the app, what code is used in which block, what protocol is used for connections between blocks, a summary of what each block does etc...
A monitoring tool as you say - and since you'll use it often you'll probably keep it up to date
Kind of more limited to a 200OK-level health check, but Structurizr does support basic checks like this (https://structurizr.com/help/health-checks) - though I do love the idea of being able to add links to an object so you could jump the log page of that service in your logging platform.
This looks nice. Personally I prefer draw.io desktop version for large complex diagrams, and use mermaid for smaller diagrams such as sequence diagrams.
Any thoughts oh lucidchart : https://www.lucidchart.com/
The Icepanel.io seems like an excellent start to an interesting project. But seems very early/alpha.
Key features - be able to distinguish between connections flowing into a hub (Outlines); have bi-directional flows to illustrate different data exchanges; colours; lack of due to huge Pro sign up ad in Diagrams view are all hinderances.
Key features - be able to distinguish between connections flowing into a hub (Outlines); have bi-directional flows to illustrate different data exchanges; colours; lack of due to huge Pro sign up ad in Diagrams view are all hinderances.
That's a beautiful website. Love the colors, mascot and the way you've laid out the information.
Tools are great, but here's the million-dollar question: how do you make people maintain the docs?
I actually have an approach here: ASCII diagrams, so i can embed them in code or a README.
It keeps things simple - you can't have a super complex ASCII diagram; even crossing lines look terrible - and there's at least a fighting chance that when someone changes the code they will at least notice the diagram is out of date.
To prevent insanity, I use a tool to help draw them: Monodraw in my case.
It keeps things simple - you can't have a super complex ASCII diagram; even crossing lines look terrible - and there's at least a fighting chance that when someone changes the code they will at least notice the diagram is out of date.
To prevent insanity, I use a tool to help draw them: Monodraw in my case.
Another question: how do you make people maintain quality docs? Sometimes I start to doubt, if it's even possible to maintain some order with bigger solutions, because even if you can force yourself to document well everything, there will be always people that either don't know solution well enough, they don't know how to prepare good documentation or they don't want to bother with it.
We have a few ideas in that area revolving around our Slackbot, keep watching for our next releases for more details.
Needs a copy editor. “Periodically” is spelled two different ways, both wrong.
Thanks for taking the voluntary role ;)
I really want to check this out but whenever I try to create an account I keep getting "broken link" errors.
Please give it another go, I've replied to your support email.
Can these be part of the source code repo and attached from ADRs?
Dark diagrams make for terrible documentation IMO.
I think this is partially why I started to hate crypto.
I was explaining to people that they were getting scammed ( they said they bought one coin) and i was looking it up since I didn't know it, so i concluded that they were scammed.
They just didn't believe me and said i was a liar. Their family friend who walked away with >50k would never do that to them.
A lot of people just don't understand cryptocurrency and greed had them losing their common sense, i was truelly disgusted by this.
Even as I had crypto until 2017 and earned a reasonable amount with it, I've started to become a non-believer in it. The existing coins are just an example of the blockchain and while the tech is great, an existing coin will never be adopted by a country. So it's futile to believe that a certain coin will become the standard.
Authorities ( for good reason) will never allow that to happen.
I was explaining to people that they were getting scammed ( they said they bought one coin) and i was looking it up since I didn't know it, so i concluded that they were scammed.
They just didn't believe me and said i was a liar. Their family friend who walked away with >50k would never do that to them.
A lot of people just don't understand cryptocurrency and greed had them losing their common sense, i was truelly disgusted by this.
Even as I had crypto until 2017 and earned a reasonable amount with it, I've started to become a non-believer in it. The existing coins are just an example of the blockchain and while the tech is great, an existing coin will never be adopted by a country. So it's futile to believe that a certain coin will become the standard.
Authorities ( for good reason) will never allow that to happen.
Ugh, i commented this reply on the wrong thread. Sorry
I love UML.
I know that is not dominant sentiment so it might get downvoted.
I worked with UML over decades now.
I refuse to use Visio, Draw.io or PlantUML for that part. I use a tool that knows UML and is constructed to quickly build UML diagrams.
Doing a Sequence diagram in draw io is something I find painful and slow.
My favorite tool is Visual Paradigm. It has the best intelligence for quickly building diagrams.
It also features two way code generation.
You can get diagrams created from code, and you can modify diagram to modify code.
From that you can get a lot of help (it is far from perfect) to create needed diagrams and also in maintaining them.
I have also used Sparx Enterprise Architect which is also very good.
In so far as creating higher level diagrams that Icepanel is most centered on, it should be greatly aided by a set of tools to discover and map artifacts in an automated manner.
Keeping diagrams up to date is a huge chore that it is nice to have help with.
Having to recode, my code, in a document for PlantUML is not something I could do either. There are some great tools for generating PlantUML diagrams and those are great.
We use some of that to generate certain diagrams automatically in our CI pipeline. When it is done running all diagrams are up to do date and placed in our documentation.
We use it to show each one of our microservices with a lot of data around then. And another one displays a lot of information about each of our container images.
Took a while to get that setup right.