[HN Gopher] Design structured diagrams, built to increase your t...
___________________________________________________________________
Design structured diagrams, built to increase your team's trust in
your docs
Author : JacobDesigns
Score : 200 points
Date : 2021-05-15 12:55 UTC (10 hours ago)
(HTM) web link (icepanel.io)
(TXT) w3m dump (icepanel.io)
| darkwater wrote:
| "Error: could not handle the request" looks like HN hug of death
| did its job.
| JacobDesigns wrote:
| Try this? http://icepanel.io/
| VWWHFSfQ wrote:
| 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.
| victor96 wrote:
| 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.
| f6v wrote:
| Tools are great, but here's the million-dollar question: how do
| you make people maintain the docs?
| JacobDesigns wrote:
| We have a few ideas in that area revolving around our Slackbot,
| keep watching for our next releases for more details.
| finnh wrote:
| 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.
| systemvoltage wrote:
| Dark diagrams make for terrible documentation IMO.
| drewcoo wrote:
| What on earth do diagrams have to do with trust in docs? Docs
| that are useful, accurate, and up to date would increase trust.
| JacobDesigns wrote:
| 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.
| jmarcher wrote:
| 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).
| deanclatworthy wrote:
| 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.
| drewpc wrote:
| > I'll never use a proprietary tool that doesn't have
| declarative syntax
|
| Can you provide an example of what you're referring to?
| petepete wrote:
| 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
| gregmac wrote:
| 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.
| Veuxdo wrote:
| +1 for declarative syntax. Diagrams-as-code is great, but
| diagramming in a _programming_ language (e.g. Python) is...
| weird.
| jasau wrote:
| Just mentioning that programming language doesn't rule out
| the option to have declarative syntax for an API.
| mattm wrote:
| Wow, this is interesting. Are there any diagramming tools that
| allow importing PlantUML to display them a little nicer than
| the examples?
| sombremesa wrote:
| There's some nicer looking ones here:
|
| https://crashedmind.github.io/PlantUMLHitchhikersGuide/
| iso1210 wrote:
| 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.
| deanclatworthy wrote:
| 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.
| iso1210 wrote:
| drawio embeds the code in the png, so you just edit it in
| situ.
| john-tells-all wrote:
| 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-...
| mroche wrote:
| 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).
| simonireilly wrote:
| 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.
| Gehinnn wrote:
| 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!
| cdnsteve wrote:
| Can these be part of the source code repo and attached from ADRs?
| powerapple wrote:
| 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?
| NicoJuicy wrote:
| 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.
| d--b wrote:
| 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.
| devgoldm wrote:
| 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
| marsven_422 wrote:
| What ever happened to the spirit of open source... Everyone
| trying to make a quick buck on some SaS scheme.
| ThinkBeat wrote:
| 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.
| rubicks wrote:
| Is anyone using dot and/or graphviz in earnest for something like
| this?
| logbiscuitswave wrote:
| 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.
| camyule wrote:
| PlantUML uses a declarative approach to diagrams and works well
| with dot and graphviz.
| css wrote:
| 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.
| edsonmedina wrote:
| If a diagram is too complex, shouldn't you just add more
| abstractions? That would simplify the refactoring too.
| JacobDesigns wrote:
| 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.
| [deleted]
| Veuxdo wrote:
| 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.
| ta988 wrote:
| I wish there would be a mixture of diagrams.net and mermaid.
| kitd wrote:
| draw.io/diagrams.net has a mermaid plugin
|
| https://github.com/nopeslide/drawio_mermaid_plugin
| Veuxdo wrote:
| What would that ideal mixture look like to you?
| ta988 wrote:
| drawio using the templating engine of mermaid. So it
| would have a "restricted mode" that matches roughly to
| what mermaid would output.
| kqr2 wrote:
| Any thoughts oh lucidchart : https://www.lucidchart.com/
| syntaxing wrote:
| Nice, I'm pretty excited to try this out for my personal
| projects. Been looking for something like lucidcharts but meant
| for code architectures.
| vishnumohandas wrote:
| That's a beautiful website. Love the colors, mascot and the way
| you've laid out the information.
| andreygrehov wrote:
| 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.
| kpwagner wrote:
| 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.
| nerdponx wrote:
| 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.
| jwalton wrote:
| 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.
| GordonS wrote:
| 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.
| victor96 wrote:
| 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.
| GordonS wrote:
| 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!
| toss1 wrote:
| 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.
| JacobDesigns wrote:
| What size of company and what industry do you work in out
| of interest?
| ta988 wrote:
| 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).
| Datagenerator wrote:
| 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
| humps wrote:
| 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/
___________________________________________________________________
(page generated 2021-05-15 23:00 UTC)