Live data from Hacker News

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

icepanel.io

21–30 of 83 posts

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

#21

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.

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

#22
post #9
post #8

Earlier quoted context omitted.

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…

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.

What size of company and what industry do you work in out of interest?

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

#24
post #11
post #9

Earlier quoted context omitted.

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

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

#25
post #16

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.

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

#26
post #13
post #12

Earlier quoted context omitted.

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.

What would that ideal mixture look like to you?

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

#27
post #10

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.

If a diagram is too complex, shouldn't you just add more abstractions? That would simplify the refactoring too.

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

#29
post #10

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.

[deleted]

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

#30
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.
Post reply on HN