Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Design structured diagrams, built to increase your team's trust in your docs

icepanel.io

Post reply on HN
Print view View original

51–60 of 83 posts

Re: Design structured diagrams, built to increase your team's trust in your docs

#51

Post by mroche »

iso1210 wrote: post #48
deanclatworthy wrote: post #18

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.

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

Re: Design structured diagrams, built to increase your team's trust in your docs

#52

Post by NicoJuicy »

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.

Re: Design structured diagrams, built to increase your team's trust in your docs

#53

Post by ThinkBeat »

This seems to be based on C4 which apparently is an heir to UML.

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.

Re: Design structured diagrams, built to increase your team's trust in your docs

#54

Post by iso1210 »

deanclatworthy wrote: post #50
iso1210 wrote: post #48

Earlier quoted context omitted.

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.

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 i…

drawio embeds the code in the png, so you just edit it in situ.

Re: Design structured diagrams, built to increase your team's trust in your docs

#55

Post by simonireilly »

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 ![](./relative/file/path.darwio.png).

It will render locally, and in GitHub, and also if you use remark or something like that, it will still render as an image.

Re: Design structured diagrams, built to increase your team's trust in your docs

#56

Post by jasau »

Veuxdo wrote: post #21
deanclatworthy wrote: post #18

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.

+1 for declarative syntax. Diagrams-as-code is great, but diagramming in a programming language (e.g. Python) is... weird.

Just mentioning that programming language doesn't rule out the option to have declarative syntax for an API.

Re: Design structured diagrams, built to increase your team's trust in your docs

#57

Post by john-tells-all »

iso1210 wrote: post #54
deanclatworthy wrote: post #50

Earlier quoted context omitted.

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 i…

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

Re: Design structured diagrams, built to increase your team's trust in your docs

#58

Post by logbiscuitswave »

rubicks wrote: post #23

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.

Re: Design structured diagrams, built to increase your team's trust in your docs

#60

Post by Gehinnn »

simonireilly wrote: post #55

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 ![](./relative/file/path.darwio.png). It will render locally, and in GitHub, and also if you use remark or something l…

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!

Post reply on HN