[HN Gopher] Nomnoml
___________________________________________________________________
Nomnoml
Author : mono-bob
Score : 590 points
Date : 2023-10-02 07:12 UTC (15 hours ago)
(HTM) web link (nomnoml.com)
(TXT) w3m dump (nomnoml.com)
| saberience wrote:
| I have a hard time understanding why any engineering team I've
| ever worked on would use this. Can someone sell this idea to me?
| Seems like a waste of time when you can knock up fast and easier
| to understand diagrams with something like Miro which also can be
| done in a multi-user environment.
| cjf101 wrote:
| One advantage for me, is that systems like this let me think
| only about relationships. This is particularly good when
| designing, or exploring how to think about an existing system.
| So for me, I get into a flow state, just connecting the dots
| logically. Even better: I can adjust the diagram just by
| adjusting the relationships.
|
| Miro and others, I am always thinking visually. It's another
| step removed from the real thought process.
|
| As you point out, these systems sometimes produce difficult to
| read diagrams. For particularly important communications, I
| will re-draw these in draw.io, or a similar sort of tool. But
| then I am thinking more about presentation, rather than
| relationship design and the tool is better for the job.
| sBqQu3U0wH wrote:
| To each their own I guess, some people like doing it this way,
| so good for them. I personally wouldn't use this either, as I
| find GUI tools faster and easier to use.
| guntherhermann wrote:
| I work with someone who is blind, and our diagrams are written
| in something similar to this (can't remember the name, but
| confluence either supports it out of the box or there's a
| plugin for it).
|
| And personally, if you're going to suggest an alternative, Miro
| is not the one. Irritating SAAS nonsense
| withinboredom wrote:
| I use mermaidjs for basically everything documentation related.
| It works in GitHub ... confluence ... everywhere. This looks
| like a much prettier version of that.
| hahn-kev wrote:
| Yeah, for me this is why nothing else can compete. If there's
| native support in GitHub it's hard to see anything else as
| better without that feature.
| withinboredom wrote:
| To me, that's also a problem. It locks out competitors
| (like this tool). It'd be great if they simply allowed
| installing arbitrary renderers on an org (basically, given
| a fenced input, output an image or formatted text).
| h0l0cube wrote:
| These mark up languages like PlantUML/Mermaid are diffable,
| mergeable, and can sit there in the repo right next to the code
| it's designing for. Many IDEs and cloud repositories support
| displaying them. Not sure if that's the case for nomnoml
| though.
| jldugger wrote:
| Three reasons:
|
| 1. I want changes to the diagram to be peer reviewable and
| understandable. 2. I want something else to manually lay out
| things, rather than have to adjust it personally on every
| addition or change. 3. I want a parsable structure I can feed
| into grafana or similar, so I can decorate the graph with
| metric data. It seems like it would be cool to have a graph of
| RPC calls and which links were red.
| cdchn wrote:
| >I want a parsable structure I can feed into grafana or
| similar, so I can decorate the graph with metric data.
|
| I don't think this can do it, but it would be cool if it
| could.
|
| Maybe someone can make another diagramming DSL for the
| Grafana Node Panel.
| jldugger wrote:
| Well, right now I have graphviz dot which should be enough
| to load in and transform as needed into whatever DSL
| desired.
| cdchn wrote:
| I don't think anything that I'm aware of converts
| graphviz dot files into Grafana Node Panels but it would
| be a good project if someone did it.
| Aissen wrote:
| One of those "text to diagram" contenders did a comparison
| website (open source) a while back: https://text-to-diagram.com/
| (nomnoml isn't in there).
| imiric wrote:
| That site is created by the maintainers of D2[1], so it might
| be biased, but I still think D2 has the friendliest syntax of
| the bunch, including nomnoml.
|
| [1]: https://d2lang.com/
| sts153 wrote:
| simple and great!
|
| a REAL tool
| archibaldJ wrote:
| gh link -> https://github.com/skanaar/nomnoml
| makach wrote:
| this just triggers my entire spectrum of love for this text-to-
| diagram, but I always struggle with increasing difficulty
| managing content as the complexity grows.
| orobinson wrote:
| I actually find this acts as a useful heuristic to bound the
| complexity of a diagram appropriately. For example if I'm
| making a diagram with Mermaid and find the code is becoming
| unwieldy, I take that as an indicator that I'm trying to stuff
| too much info into one diagram and I should split it into
| separate diagrams or redo it at a higher level of abstraction.
| nicce wrote:
| If you edit these manually - yes. Usually these sort of tools
| are meant to generate output programmatically. Otherwise
| dragn'drop could be more useful.
| MichaelMug wrote:
| Nice. Perhaps an Obsidian plugin?
| pfix wrote:
| https://github.com/Daeik/obsidian-nomnoml-diagram
| estomagordo wrote:
| As a newcomer to Obsidian, I have no idea how to get the svg
| to render side-by-side.
| zubairq wrote:
| Really amazing, think I'll be using this quite alot now!
| rurban wrote:
| The last e label is missing in this sample
| hnbad wrote:
| Neither the end node nor the start node have a visible label. I
| suspect this is intentional but they shouldn't take a label
| argument then.
| planede wrote:
| The label seems to serve as a reference. If have `->
| [<end>a]` and `-> [<end>b]` then that's different than having
| two instances of `-> [<end>a]` from different source nodes.
|
| Being able to visibly label them would still make a lot of
| sense.
| ororroro wrote:
| Getting a good layout is too dependent on the order of
| definition. I can see that becoming unsolvable for the user for
| large diagrams but seems ok for small ones. For example the
| following gives an ugly yet valid layout of the example:
| [more loot] no ->[<end>e] [<start>start] ->
| [<state>plunder] -> [<choice>more loot] -> [start]
| [Pirate| [foul mouth]<:-[beard] [parrot]--[beard]
| ] [<table>mischief| bawl | sing || yell | drink ]
| [<abstract>Marauder]<:--[Pirate] [Pirate] -
| 0..7[mischief] [<actor id=sailor>Jolly;Sailor]
| [sailor]->[rum] [Pirate]-> *[rum|tastiness: Int|swig()]
| [sailor]->[Pirate]
| zoogeny wrote:
| One problem with these tools is that even if you manage to get
| a good layout for a document then as soon as you need to
| add/remove/update then you have to wrestle with them all over
| again.
|
| I've used a few of these code-as-diagram products because I
| dream of a world where technical documentation, including
| diagrams, are part of the source code of a project. But my
| experience is that getting acceptable layouts, especially for
| external distribution but also just for internal use, is
| arduous.
|
| And that frustration leads to at least two possible undesirable
| outcomes: the diagrams become unreadable or the diagrams become
| unmaintained.
|
| To be honest, the idea of code-reviewing the documents during
| check-in is also a myth. In general the diffs on these kind of
| documents are extremely difficult to grok. It is almost
| impossible to meaningfully check the document is correct
| without rendering it and reviewing the output.
|
| It is the kind of thing I really wish worked. Maybe one day it
| will become a solved problem.
| MilStdJunkie wrote:
| If you don't mind my asking, what aspects of "acceptable
| layout" is usually the first to get busted? Do the fonts
| overstrike? Does it shrink down so small the lines don't
| render? Is it just that all the boxes get thrashed in a
| blender and the diagram looks completely different?
|
| I'm extremely excited about using WireViz[1] to automate
| wiring harness diagram creation, and if I can, I'd like to
| know the speedbumps before I hit them. I'm thinkin generous
| linking between diagrams will be one path - keep the
| individual diagrams fairly small in scope, link 'em together.
|
| [1] Project:: https://github.com/wireviz/WireViz SandboxP::
| https://kroki.io/#try [select Diagram>WireViz]
| jldugger wrote:
| In my experience with graphviz, the two layout problems
| are:
|
| 1. the lines are not distinct -- they can bunch up and
| overlap, making them untraceable 2. Logical groupings are
| hard to maintain unless they are highly connected.
| zoogeny wrote:
| I have two main complaints that jump to the top of mind.
|
| The first is lines and when they merge and when they cross.
| Not all lines from two separate boxes to a third box ought
| to merge, but some should. Crossing is inevitable in most
| complex diagrams but expressing where the crosses ought to
| happen is not something I have had any success with.
|
| The second is that some diagrams are like a story, with a
| beginning a middle and an end. Using horizontal, vertical
| and even diagonal relationships visually can be important.
| Keeping that story clearly organized has always been a
| challenge and even requires some iteration when doing the
| drag-n-drop thing. Rarely does the story of the diagram
| just happen to pop out using the default placement
| algorithms of any text-to-diagram tool I have used. And so
| I find myself tediously massaging the order of statements
| or whatever crude controls I'm given to painstakingly move
| boxes into some semblance of the story. And then, once I've
| managed to convince the diagram to be as close as I can to
| what I envision, I realize I missed a key component or
| connection.
|
| The last thing I'll point out is more a preference. In
| general, the output tends to be quite ugly to my eye. There
| are times I have been responsible for generating systems
| diagrams for potentially big deals. In those cases we want
| to put the best foot forward to external entities. There is
| something uncanny valley, or like generated text-to-speech
| in the appearance of the documents that can be undesirable
| in many contexts.
| jrowen wrote:
| It seems like a situation that would benefit from separating
| the logical/structural definitions from the
| layout/presentation rules, much like HTML and CSS. The
| structural side would be clean and easy to maintain and all
| the fiddly presentation stuff would have space to be
| specific. Constraint-based layout rules a la flexbox would
| seem useful. Has anyone tried that approach?
|
| Edit: You're probably still going to have to render it as
| part of the review for non-trivial changes but when the
| visual result matters I don't see any way to avoid that.
| dangets wrote:
| I've thought the same quite a bit.
|
| On one end of the spectrum you could use something like SVG
| if there were standard or dominant tools used to
| import/export, but then you lose the ascii readability
| benefit of tools like this, dot, or d2.
|
| It'd be nice to have a mixed text & GUI editor for something
| like Pikchr diagrams.
|
| https://pikchr.org/home/doc/trunk/homepage.md
|
| https://d2lang.com/
| zoogeny wrote:
| Something in the direction of SVG is probably correct. I
| like the idea of having arbitrary paths available. One
| common annoyance with existing tools is that there is
| sometimes a lack of shapes and colors that express what I
| want. I find the same even with Google's rudimentary
| drawing tools.
|
| It may be the case that these diagraming tools are aiming
| to be too high level. But where the middle ground lies I am
| not too sure. It is nice to express high level concepts
| like "Actors" or "Process" or "Class". And it is nice to
| have convenient syntax for things like UML sequence
| diagrams. I don't think it would be an equal exchange to
| give me rectangle and line drawing primitives since now I'd
| have to manage the connections by hand. And there would be
| no semantic meaning in such text formats, even if you
| managed to retain "readability".
|
| But on the other hand ... to get the diagram solutions into
| a visual format I like I tend to lose the readability
| anyway. If you have several boxes with many connection -
| even reading the text becomes difficult. It is hard to keep
| the connections in your head once they get 2 or 3 hops
| deep. And you end up with 15 lines of connection spam, like
| "EntityA -> EntityB", "EntityC -> EntityB", "EntityA ->
| EntityD". And you end up trying to manage hierarchical
| relationships, fussing over what is the correct order to
| declare things, like manually doing your own dependency
| resolution. So maybe strict readability isn't really even a
| property I can expect to maintain.
|
| I really hope it gets solved one day.
| Veuxdo wrote:
| This pirate example is not doing us any favors. Is there a way
| to arrange these jumble of words in a way that makes any sense?
| p1mrx wrote:
| Arrr, it be fine as it be, now sail off ye scallywag.
| p1mrx wrote:
| Edit: If ye wish to see, Ctrl-C, Ctrl-V.
| kstrauser wrote:
| I get what you're saying. What's the relationship between
| beard and parrot, if all you had was the text of the diagram
| and didn't already know nomnoml? A great example would use
| new syntax to illustrate relationships you already understand
| to demonstrate how to write them.
| Savely wrote:
| We need another tool that would optimise permutation of
| statements for least overlap in the resulting diagram.
| bmacho wrote:
| edit: I thought that it goes top to down, but no, it determines
| order other ways. Original Pirate table:
| [Pirate| [beard]--[parrot] [beard]-:>[foul
| mouth] ]
|
| parent posts Pirate table [Pirate|
| [foul mouth]<:-[beard] [parrot]--[beard] ]
|
| this is upside down. Defining beard and parrot the order we
| want them to appear doesn't help: [Pirate|
| [beard] [parrot] [foul mouth] [foul
| mouth]<:-[beard] [parrot]--[beard] ]
|
| it is still upside down.
| ororroro wrote:
| Thanks for treating this as a puzzle. I think it proves the
| point that you either need to reverse engineer the layout
| engine in your head or guess and check to get good layouts.
| ludovicianul wrote:
| I find https://www.structurizr.com/ more suitable for my needs.
| vijucat wrote:
| Very cool. Please do sequence diagrams with swimlanes; they're
| the most useful.
| mactavish88 wrote:
| Very cool!
|
| It blows my mind though how the moment that someone offers free
| stuff, the first comments are people asking for more free stuff.
|
| If I wasn't paid to work full time on open source software, I'd
| think very carefully about whether to do any open source work
| nowadays.
| j-a-a-p wrote:
| > It blows my mind though how the moment that someone offers
| free stuff...
|
| Try to launch a free service for consumers and experience how
| they are _entitled_ to stuff just because you offer this
| service.
| budoso wrote:
| Personally I think posting to Github is the offering part,
| posting the tool to HN is definitely an invitation for
| opinions.
| zeroxfe wrote:
| > If I wasn't paid to work full time on open source software,
| I'd think very carefully about whether to do any open source
| work nowadays.
|
| I've been maintaining open source software for two decades now,
| and I still love it when people ask for more stuff. It signals
| engagement and satisfaction and gives me very concrete
| directional guidance around where I should take my software.
|
| I'm under no obligation to deliver on those requests.
|
| My day job pays my bills, my open source stuff brings me joy.
| sneak wrote:
| Reading requests is not burdensome. It's just feedback.
| thangngoc89 wrote:
| I wouldn't count those comments as asking for more free stuff.
| I would think of them as feature requests, ideas, suggestions.
| Whether or not to implement them is totally up to the author,
| and the author could charge for those if they decide to
| implement it.
| mactavish88 wrote:
| [flagged]
| oblio wrote:
| I'd have to at least switch tabs and that's very demanding.
| thangngoc89 wrote:
| Isn't that the point of posting/ commenting on HN? So that
| we can discuss about the post? I see something on HN and
| after checking it, I would definitely comment on HN first.
| mactavish88 wrote:
| As someone who has been working on open source software
| for 5 years now, GitHub issues are my primary source of
| truth for what users want and how to go about
| prioritizing features.
|
| If people can't be bothered to log an issue or thumbs-
| up/comment on an existing one, it can't be such an
| important thing to them.
| dan_mctree wrote:
| Those who log issues are the hardcore users crowd that
| are bothered by something small, whereas new potential
| users that bounce because of something important
| generally don't bother making issues. You may be missing
| out on a lot of critical issues such as limited
| documentation and confusing API aspects by ignoring other
| channels of communication.
| __MatrixMan__ wrote:
| This is probably true, but it's also bad.
|
| It's generally pretty easy to look at the tone of how
| recent issues are handled and know if the maintainer is
| drowning and would prefer that you keep the noise down,
| versus whether they're likely to feel energized by
| interacting with enthusiastic users.
|
| You don't have to be hardcore to leave helpful feedback.
| If you think it's the latter, go file an issue.
| [deleted]
| hk__2 wrote:
| That's your experience; I've been working on open source
| software for 10 years now and GitHub issues are just one
| source of feedback; Reddit/HN, other forums, conferences,
| anything can be useful to meet your users and get ideas
| on what to improve.
| Angostura wrote:
| And you get a different subset of new potential users on
| HN who wouldn't be aware of the project on or off GitHub.
| josephg wrote:
| Yeah; comments fill a different use case. And for that
| reason I still find comments interesting.
|
| I'd never write a github issue unless I have a clear use
| case for a feature, or a clear reproducable bug. And on
| the receiving side, I hate unclear discussion style
| issues - "This is cool but its slow when I do (hacky
| unsupported thing)".
|
| But with comments you surface much more "raw" reactions
| to things. "Oh cool - I didn't think about the problem
| like that". "I've always wanted something like this for
| (some weird problem)", or "How come everyone who tries to
| solve this problem uses approach X? Is there a reason
| people don't use approach Z?".
|
| Maybe as a maintainer, the beauty of HN comments is that
| you don't actually need to reply to them. Github issues
| sort of demand a response by their very being. If you
| leave them, they get in the way and make the issue
| repository basically useless. If you close them without
| responding, its kinda rude. And responding takes time.
| Comments, on the other hand, can just be comments. Its
| lovely.
| wolletd wrote:
| First you complain that people are asking for more free
| stuff, then you complain that they are asking in the
| wrong place?
|
| Whats your point? Aren't people allowed to discuss stuff
| other people share with them on the internet?
| JadeNB wrote:
| > Whats your point? Aren't people allowed to discuss
| stuff other people share with them on the internet?
|
| I think their point might be: such discussion might be
| fun for users, but could be unpleasant or unproductive
| for the maintainer. That's a totally different concern to
| express from "don't talk about this at all." Personally,
| the first thing I do with new software is see what I can
| do with it, and what I might want to do with it, and I
| can get carried away in a discussion thread. There's no
| harm in remembering that the maintainer might be here
| reading, and keeping their reaction in mind is no huge
| ask.
| shadowgovt wrote:
| Philosophically, I try to embrace the zen of remembering
| that at the end of the day, while I would love to be
| helpful, strangers' concerns are not my concerns.
|
| If I'm feeling overwhelmed, if I'm feeling burnt out, if
| the comments are too much or are unhelpful or are rude...
| I can tune them out. As the author, my goal was to solve
| a problem I had. I solved it. If the solution benefits
| someone else, that's gravy, but I've already put my
| energy back into the universe by sharing my solution one
| time in the first place.
|
| Maintenance is a choice. Share and enjoy.
| oblio wrote:
| Nice comment! Could you please provide a few more details about
| what you mean exactly?
| barthvr wrote:
| The first two comments (by timestamp) are one guy (OP) asking
| for an Obsidian plugin, and the second one is a guy asking
| for the implementation of swimlane diagrams.
| waveBidder wrote:
| it's hard to tell if you're mocking the grandparent or people
| making feature requests
| oblio wrote:
| Well, kind of both :-)
| dkobia wrote:
| Thankfully many open source projects stem from people solving
| for their own problems then benevolently sharing their
| solution. It isn't for everyone and we are all grateful for
| their contributions.
| CapsAdmin wrote:
| > It blows my mind though how the moment that someone offers
| free stuff, the first comments are people asking for more free
| stuff.
|
| If you create something from the perspective of "I had to make
| this on my unpaid spare time..", then requests for additional
| work do seem annoying.
|
| But is that the case here?
|
| If I made a utility I thought other people could also benefit
| from I'd personally be open to suggestions. I'd ignore a lot of
| them, but every now and then someone requests something
| interesting that sparks motivation to expand the utility.
| z500 wrote:
| I have a tool I've been working on on and off, and after
| several years it's actually working. But I was barely smart
| enough to do even that. If people actually started using it
| and asking for features that would be a nightmare for me lol
| BossingAround wrote:
| You can always say "feel free to fork my project, I
| currently don't have the bandwith." That's absolutely
| within the spirit of open source.
| lcnPylGDnU4H9OF wrote:
| "No" is your friend in such scenarios. "Because I made it
| for me and I don't need that" is your other friend if
| people are insistent. (A screenshot of the "fork" button on
| Github might be a third, rather muscly friend who doesn't
| like to talk.)
|
| I do understand the desire to be helpful but one should put
| themself first when it comes to fulfilling requests. Just
| in case anyone gets here and is similarly discouraged.
|
| (Good job finishing the features you wanted!)
| xoac wrote:
| Do you maintain any popular open source projects?
| CapsAdmin wrote:
| I have one popular project I've worked since around 2010.
| Lately I've let some of the long time users who can also
| code maintain it though. It's a character creation editor
| for a game, a bit like second life in a way. (it's called
| pac3 for garrymsmod)
|
| I don't have any numbers apart from steam workshop which
| claims 800k current subscribers, though that doesn't say
| anything about active users. But there are a lot of
| tutorials, discord groups, etc centered around this so I'd
| call it popular.
|
| The way I maintain this project is not very professional. I
| maximize my own joy first because if I don't have that, I
| can't work on the project.
|
| The community is loud, maybe because the community is also
| mostly young gamers. Sometimes I break things and people
| complain. Sometimes they can call me names, write long
| emotional posts about how I should revert something and how
| everything was better in the past version.
|
| But overall I enjoy working on the project and seeing the
| amazing things people create with it that I could never
| foresee.
|
| There are several channels for feature requests (github,
| discord, steamcommunity), but I don't actively follow it. I
| usually check when I'm not sure what to do but still feel
| like working on it.
|
| Sometimes people contact me directly to ask if I can add X
| feature. Sometimes that works.
|
| For features in general I try to implement something
| everyone can benefit from, since the editor allows you to
| create things from smaller building blocks, I'd rather make
| those smaller building blocks necessary to create the high
| level feature that was requested.
| f1shy wrote:
| I see those requests as gratuitous feedback and ideas that
| could be useful. I'm glad to have more requests. By no means
| I'm going to implement them, but maybe some request triggers
| useful ideas.
| dingosity wrote:
| Meh. I make free stuff and I'm completely okay with people
| _asking_ for more free stuff. I might be thinking of adding
| something you say you need, so it 's cool to know what other
| people's requirements are. If they're simple to implement, and
| other people submit a test case for it, I'm fine with
| enhancement requests.
|
| HOWEVER...
|
| I've had a few people who say things like "OMG. YOU MUST DO IT
| THE WAY I THINK YOU SHOULD DO IT" or "ADD THIS FEATURE OR YOUR
| NOT A _REAL_ OPEN SOURCE CONTRIBUTOR. " And that is definitely
| annoying. I have a thick hide and don't mind just ignoring
| those people, but that shouldn't be the default assumption. The
| people who work on open source projects are people, so don't be
| a pushy jerk when you're requesting features from FLOSS
| projects.
|
| ALSO...
|
| Let people revel in the approval of their peers before pointing
| out things you would have done differently. This is a cool bit
| of kit.
| blagie wrote:
| The language is very, very nice.
|
| However, if I ran into this incidentally (not posted to HN for
| review), I would never use this. I'd see the lack of a github
| link on the top right, and assume it's a some kind of startup
| making some prototype hosted tool.
|
| The only way to find out this is open-source is to click "about,"
| read to the third paragraph, see github mentioned, click through
| the link, and click on the license.
|
| My major piece of feedback is to add a github link to the icons
| at the top-right of the page. A .org might also be nicer than a
| .com.
|
| To people asking why this and not a graphical tool?
|
| To me, the overhead to moving a graphical tool is very large:
|
| 1) I like being able to manage files on github and be able to use
| common tooling.
|
| 2) If someone (including myself, two years later) needs to
| install Vizio, Illustrator, or whatever other tool to edit my
| diagrams, pay for a cloud service, or worse, recover something
| which was hosted in a discontinued tool, I'm SOL.
|
| 3) Discovery is big too. I can use normal search tools to find
| things. If something is locked away in a .ai file, a .docx file,
| or a cloud service, and I lose it, it's likely lost forever.
|
| 95% of the cost of most projects is maintenance, and even if I
| invest 10x the time up-front into making a diagram in a tool like
| this (e.g. an hour to learn it, tweak it, and get the diagram I
| want, instead of 5 minutes in my favourite GUI), that will pay
| much than an hour in dividends down the line. I use Markdown,
| LaTeX, and similar for large or important documents because, in
| the long term, they save time.
| scbrg wrote:
| > However, if I ran into this incidentally (not posted to HN
| for review), I would never use this. I'd see the lack of a
| github link on the top right, and assume it's a some kind of
| startup making some prototype hosted tool.
|
| Yeah, it's absolutely horrible when the GitHub link is in the
| bottom right rather than the top right. _Completely_
| unforgivable. Geez.
|
| Do (Free|Net|Open)BSD and GNU tools qualify as open source? No
| GitHub link as far as the eye can see :)
| blagie wrote:
| What's in the bottom right is still not the same. Plenty of
| projects use github issues for issue tracking without being
| open-source. This links to the github issues. It's still
| three clicks to find out it's open-source. In addition, the
| upside of following standard patterns is pretty well-
| established. Most of us are tuned to ignore pop-overs.
|
| Ways I've seen this done:
|
| - Clear github icon (visual cue)
|
| - "Fork us on github" template
|
| - Adding the words "open-source" somewhere (or even XXX-
| licensed). The "about" page could start "An open-source tool
| for drawing UML diagrams based on a simple syntax."
|
| There's no reason to go over-the-top. Again, the reason
| people post things to HN is generally to generate visibility
| and to gain feedback. People don't write feedback to be mean
| but to help projects improve.
|
| It's not "completely unforgivable" but I gave a bit of simple
| feedback which might reduce friction a bit and which would
| take a few minutes to implement. I appreciate similar
| feedback on my projects. In this case, for me (n=1), I've
| been derailed from adopting projects based on similar levels
| of friction. I will pull up a many things, prune them pretty
| quickly, and then do a deep dive into the most promising.
| I've always found user studies and friendly reviews helpful
| for avoiding these sorts of frictions in my own work.
| darkwater wrote:
| I think that the main complaint was a lack of prominence to
| what the thing actually is, and its license.
| f1shy wrote:
| Was only a feedback.
| dizhn wrote:
| Nowadays even with a GitHub link or claims of being open source
| you have to go check the repository to see what license they
| actually have and what percentage of the source is actually
| there. Some repos even have only binaries and some have the
| source for the open source projects they use.
|
| There's actually another category. Open source software with
| paid plugins. I always wonder what happens when someone adds
| similar functionality to the open source version.
| ahartmetz wrote:
| I dunno, is it even still ...allowed... to have Free / Open
| Source software that does not live on GitHub? Because that
| exists. Though admittedly it's usually mirrored on GitHub.
| hoosieree wrote:
| If you're not freely donating your time and energy to
| improving the proprietary dataset that powers Copilot, can
| you even call yourself Open Source?
| carapace wrote:
| It's truly astonishing and disheartening how completely MS
| has routed the Free and Open Source movement. (Even before
| you get to Copilot.)
| eru wrote:
| This was very confusing, until I found the 'about' button.
|
| I guess I'm leading a charmed life, because I can not recognise
| UML on sight? (I thought at first this was describing a grammar
| of fake pirate language or something.)
| IshKebab wrote:
| The way to recognise UML is by the wide variety of arrow styles
| that nobody can remember. I'm 90% sure that's the main reason
| it didn't catch on.
|
| You have to _learn_ UML because of the stupid arrows. Compare
| it to something like this which acknowledges the fact that
| nobody is going to casually memorise 10 different styles of
| arrow just to read occasional UML diagrams:
|
| https://buck2.build/docs/concepts/concept_map/
|
| Much better.
| dathinab wrote:
| it's not really UML, at least not standard conform I think
|
| through that's kinda true for a ton of tooling using the word
| "UML"
|
| and in many case you also somewhat want something which is less
| precise (and verbose) then UML theoretically is
| vidarh wrote:
| > and in many case you also somewhat want something which is
| less precise (and verbose) then UML theoretically is
|
| This tends to be "the" big problem with UML (and similar):
| Very few people care about, or have a reason to, stick 100%
| to UML. They want to "speak diagrams", and just like written
| or spoken language, our syntax and semantics is context
| dependent and dependent on the dialect and speech patterns
| and understanding of those we speak to.
|
| So the "UML" people learn is often a dialect of sorts closer
| or further from the formal grammar, and a lot of tools fail
| to take that into account and try to force you into
| conformity. We accept that for programming languages, yet we
| still use pseudo-code in all kinds of contexts, but diagrams
| are one step up - one of the things we "escape to" when
| writing formal code is too complex or we want to explain
| things to people who don't know or care about the details.
|
| There's a significant strain there between those conflicting
| goals of diagrams as communication, and the evolution of CASE
| tools that wants diagrams to be formal, that is much closer
| to how we deal with natural languages (people arguing over
| formal use vs. slang) than with programming languages, and
| it's fascinating.
| layer8 wrote:
| It's a pity, because one benefit of UML would be that
| everyone speaks the same language. Before UML, there were
| many different modeling notations [0], and the goal with
| UML was to create a single interoperable unified language.
| This was successful insofar as it displaced the previous
| object modeling languages. However, it would be nice to
| have that benefit of a modeling lingua franca not only in
| modeling tools, but for casual usage as well.
|
| [0] https://en.wikipedia.org/wiki/Object-modeling_language
| vidarh wrote:
| Yes, but the problem of this thinking is that when
| communicating we inherently look for shortcuts and
| shaping language to the context rather than sticking
| strictly to a grammar and a dictionary, and to be
| successful at defining a natural language (and that
| includes diagrams) you need to accept that the job is 90%
| _describing reality_ and 10% trying to shape it. If that.
|
| UML has been reasonably successful where it described
| reality, or tried to gently shape things by proposing
| things that were close to how most people already did
| things. Much less so where it tried to prescribe a
| reality not aligned with how people communicates, or
| where it has not kept up with the way that has evolved.
| It'd be more successful at being a lingua franca if the
| focus was more on documenting how people actually use
| diagrams, and just provide gentle nudges in one or the
| other direction where use is inconsistent.
|
| I think this is also why so many people hate UML
| _tooling_ - because it forces you to communicate in this
| strange dialect that is very different from how most of
| us communicate with diagrams, and that most people find
| awkward.
| dathinab wrote:
| I think the problem comes from the difference between
| "modelling" as in the CS field of modelling and diagram
| generation for documentation purpose.
|
| They are fundamentally two different use-cases which just
| seem similar if you ignore all the subtle but important
| details.
|
| But UML tries to bridge both by having something you
| roughly could describes of "layers" of details.
|
| But for documentation, especially tutorials, well suited
| diagrams aren't often just simplified by
| omitting/grouping details or similar. They are often
| simplified in ways which makes them subtle wrong in ways
| anyone getting started with the software can ignore and
| (hopefully) a foot note about this wrongness.
|
| And most times for most people it's only ever used for
| less formal diagrams instead of "proper modelling". And
| more often for on-boarding/tutorial documentation then
| for deep technical documentation.
| tannhaeuser wrote:
| UML sucked so much, it took OOP down the drain along with
| it. Unfortunately, UML also had to contaminate nascent
| BPM modeling, by making BPMN a fscking "profile" of UML.
| I'll never forget the look of once motivated process
| modelers when they learned they need "stereotypes" and
| such - the result of their modeling was more like a
| psychoanalysis and beyond useless. Ever had to deal with
| RMI, EMF, MOF, and UML's weird and unsound meta-modelling
| "in itself" for exchanging model data modulo the worst of
| XML? To hell with it.
| [deleted]
| sBqQu3U0wH wrote:
| These tools show up from time to time here, and I can appreciate
| the technical side of things and effort put into building the
| tool. However, I cannot imagine using something like this in
| practice - either at work or for my own uses. It's so much easier
| just to select, drag and drop graphical elements instead of
| spending time learning a specific markup language and typing
| everything out, hoping that the elements will appear
| approximately where you wish they would. Maybe it's not too bad
| for very simple diagrams but unmanageable for anything complex.
| All in all, I think it does not solve any problems and merely
| adds an additional layer of complexity.
| perrygeo wrote:
| > It's so much easier just to select, drag and drop graphical
| elements instead of spending time learning a specific markup
| language and typing everything out
|
| You state this like a fact. A GUI might be your personal
| preference but markup is preferred by many. It takes me an
| order of magnitude longer to learn where all the buttons are
| than it does to internalize markdown syntax from a few good
| examples. In a GUI you spend time futzing around with visual
| details, In a markup chart you spend time building and
| communicating a coherent mental model. The difference in output
| quality is apparent to me.
|
| There's an analogy to programming: sure we have visual
| programming tools but who uses them? they break down when
| things get mildly complex. A markup driven charting tool lets
| me edit in the comfort of my chosen IDE, check it into source
| control to collaborate, renders live instead of checking in an
| image artifact, and has clearly-defined semantics (ie not just
| a pile of incoherent boxes and arrows). IMO, it's superior in
| every way except fine-grained control of the layout (which is a
| fine tradeoff for me - I want my readers to focus on content -
| consistency is more valuable than styling). If your purpose is
| communicating complex ideas (not making a pretty picture)
| markup-based charts have some distinct advantages that you just
| can't get from a point-and-click interface.
| sBqQu3U0wH wrote:
| >There's an analogy to programming: sure we have visual
| programming tools but who uses them?
|
| I really don't think this is a good analogy. Clearly
| presenting an idea / architecture / model / workflow at a
| high level by creating a graphical representation is quite
| different than making an application does a lot of things at
| a low level (e.g. handling user interactions, processing
| data, providing GUI, communicating with other systems,
| handling errors).
|
| I agree there may be some benefits to that but I guess it
| also depends on what kind of diagrams you are making. For
| example, I would never ever draw UML diagrams in markup. I
| want to be in control how elements look, where they are
| placed, where and how lines are drawn and where and how they
| are shown. In my experience, automatic placement even on GUI
| diagramming tools suck 99.9% of the time.
| vekker wrote:
| I use PlantUML a lot, for communicating complex technical
| designs for juniors to implement for example, or simply for
| documentation.
|
| It's nice to have your diagrams as readable code which you can
| check in with the rest of your git repository and embed in
| READMEs, and the syntax is really intuitive and easy to learn.
| I haven't made the comparison with this particular tool yet,
| but in general I'd recommend this practice of including
| diagrams with your docs.
| Cerium wrote:
| I have been using PlantUML a lot. For me the effort of
| drawing a diagram in an external tool and then exporting it
| seems like such a waste compared to adding source code that
| compiles into the diagram I need.
|
| As a nice bonus, GPT-4 is pretty good at generating valid
| PlantUML. I have given descriptions of the diagram I want and
| gotten results that have gone into docs unchanged.
| vekker wrote:
| Yep, GPT is nice for speeding up the process. I've gotten
| in the habit of actually speaking out loud the desired flow
| of events in a system and transcribing it, and then turning
| that text into sequence diagrams with GPT4.
| pantalaimon wrote:
| With pandoc-plot [0] you can even include them in your
| markdown documents and render it all to a nice PDF or website
| using pandoc.
|
| [0] https://github.com/LaurentRDC/pandoc-plot
| Veuxdo wrote:
| From last year: It's Time to Drop Drag-and-Drop Architecture
| Diagramming [0]
|
| [0]https://www.ilograph.com/blog/posts/its-time-to-drop-drag-
| an...
| laserbeam wrote:
| I once worked on a project where the state of a file was
| basically a graph (similar to programming languages where users
| actually manipulate an AST). Our tests would simulate changes
| on that graph and check invariants every for every build. We'd
| spend hours of our weeks looking at long logs describing steps
| to reproduce a thing.
|
| One day, someone on our team had the brilliant idea to log the
| state of the program as a dot graphviz text file and just
| render it with the tool. Our debugging effort was instant all
| of a sudden.
|
| Sometimes these tools are amazing at visualizing data more than
| at building diagrams. It's surprisingly easy to generate valid
| text files programmatically. Note that I'm talking in general
| about this class of tools, not nomnoml specifically.
| modernpink wrote:
| Similarly, I couldn't imagine not having your diagrams as code,
| enabling easier versioning, updating and collaboration over the
| UI created ones.
| ljm wrote:
| Text-based versions are much better for accessibility. A screen
| reader or text to speech software can describe a textual
| representation of a diagram much better than your WebGL
| equivalent on a zoomable canvas.
| hk__2 wrote:
| > Maybe it's not too bad for very simple diagrams but
| unmanageable for anything complex
|
| On the contrary, I use drag&drop tools for very simple diagrams
| but prefer using PlantUML for anything complex because its
| text-based interface makes it easy to generate, diff or store
| in a git repository. The best of both worlds would be a text-
| based tool to hold the semantics of your graph, and then a
| drag&drop interface to fix the layout.
| agileAlligator wrote:
| > The best of both worlds would be a text-based tool to hold
| the semantics of your graph, and then a drag&drop interface
| to fix the layout.
|
| Exactly this, I wonder why no one has come up with it yet.
| Maybe you could embed the layout details like coordinates of
| elements inside the markup in a separate section?
| Pxtl wrote:
| I've seen tools that work like this - Microsoft's earlier
| kicks at entity framework tried to do it for SQL table
| block diagrams. They would constantly get out-of-sync as
| merges happened and were generally a pain to manage.
|
| I'd rather a tool just let me give it hints of "this is an
| important block put it somewhere high visibility" and "this
| is semantically the root of a tree" and stuff like that,
| then just focus on having a good clean layout engine.
| Exuma wrote:
| How does plantUML compare to this
| totetsu wrote:
| I got quite far asking an LLM to type it out for me. and I got
| some nice diagrams to visualize the project I was thinking
| about.
| withinboredom wrote:
| I decided to ask the bing bot to type one out for me, and it
| told me "no". When I asked it why, it told me it was because
| it wasn't "creative" so it wrote me a poem in Python. I then
| asked it to write a diagram that was funny. It told me "no"
| because it wouldn't be creative.
|
| :sigh: technology.
| vidarh wrote:
| GPT4 was surprisingly good at generating dot (Graphviz) files
| when I tried, and even managed to do reasonable visual layout
| of nodes (it's an interesting test, both because reasoning
| about visual constraints in text is tricky and because good
| diagram layout algorithms are complex)
| fkyoureadthedoc wrote:
| It's decent at mermaid too, but the one time I tried it for
| something complex there I found it was just easier to do
| the diagram myself
| vidarh wrote:
| Yeah, it's surprisingly good, but definitely not _good
| enough_ to rely on for that. It was fascinating to probe
| the limits of it, though.
| PaulRobinson wrote:
| Reasons to make the effort to do this in markup:
|
| 1. You can build tools to automatically generate these diagrams
| from existing software quite easily. I've used tools like this
| to generate diagrams that were impractical documentation (150+
| sheets of A4 when printed), but showed class or module
| dependency hotspots in a way that would have taken weeks to
| understand from the code alone: a picture speaks a thousand
| words, and getting your code to give you a picture is useful.
|
| 2. You can version control them - and see change history - more
| easily through a markup/code approach than a GUI approach. When
| teams collaborate over a complicated piece of design, being
| able to see who contributed what and when in a diagram is as
| useful as it is seeing it for a piece of code. I'd argue the
| first responsibility of a programmer in a modern team is to
| communicate, and to do so in a collaborative fashion. Code,
| tests, documentation, should allow easy collaborative
| understanding, editing and iteration. Diagrams that don't have
| editable markup make this harder in a small way.
|
| 3. The semantics of the markup actually make you think through
| what it is you're trying to express. It's easy to draw a line
| connecting two shapes but what does that line actually mean? I
| find when I'm typing up markup for a diagram, this becomes
| something I more consciously consider.
|
| 4. A markup standard means there is likely to be multiple tools
| that support the reading, editing and creation of the artifacts
| you create. Some people feel it's easier to use a WYSIWYG word
| processor, but I think we can all agree that Markdown is a
| useful innovation that has stimulated some experimentation and
| development in the text editing domain.
|
| 5. Most "hand-drawn" GUI-based diagrams look ugly (most
| programmers can't design diagrams well), but using an algorithm
| to make layout choices provides consistency and better layouts.
|
| 6. Many "hand-drawn" diagrams are full of style
| inconsistencies. With a markup + parser = diagram approach, you
| can enforce a house style, update that style easily, and
| everybody's diagrams in a doc look aesthetically similar rather
| than each individual's personal preference on line weights and
| arrow styles. It's a bit like separating HTML and CSS - hard to
| do in a GUI-only approach. In larger teams with a dev wiki, all
| the diagrams looking similar is just nicer.
|
| YMMV, but I'd give this approach serious consideration - this
| tool looks great, but there are others, and it's worth
| evaluating them if one doesn't impress you. I'm a graphviz guy,
| but I might consider looking at this more closely.
| zimpenfish wrote:
| 7. You can put them in the source where they are relevant.
|
| Got a hairy state machine? Stick a comment at the top with
| something like nomnoml's syntax and anyone can follow what's
| going on without having to trace through the code.
| lelanthran wrote:
| > 7. You can put them in the source where they are
| relevant.
|
| > Got a hairy state machine? Stick a comment at the top
| with something like nomnoml's syntax and anyone can follow
| what's going on without having to trace through the code.
|
| For that use-case a markup graph language is a poor
| solution. Use https://asciiflow.com instead to produce
| something that people can digest without needing a third-
| party tool that may not even exist anymore.
| zozbot234 wrote:
| > You can build tools to automatically generate these
| diagrams from existing software quite easily.
|
| FWIW, Doxygen does diagrams-from-code out of the box. It's
| mostly a code documentation/literate programming tool, but
| also useful for these reverse engineering tasks starting from
| an existing codebase.
| bbor wrote:
| I think the big gain here is that's it's LLM-readable. If you
| make a WYSIWYG GUI backed by a plain-English format like this,
| it becomes MUCH easier for LLMs to understand and help you.
|
| And I think they've gotten to the point where "how can LLMs
| change this workflow" is a much more impactful question than
| basically any other UX improvement
| thedudeabides5 wrote:
| Everyone wants drag and drop, no one wants to build it.
| Pxtl wrote:
| Either way, regardless of whether it's easier - the software
| world is driven by the power of plain text. Text is king. Text
| lets you diff, lets you git, lets you pull-request, lets you
| grep, etc.
|
| Look at the popularity of Markdown, a syntax that is just
| "simple html but it's easy to read in plain-text form". Or
| YAML, which is just "JSON and XML that doesn't make your eyes
| bleed, but has the worst type-inference ideas ever".
|
| Yes, GUI tools can help. Doing image-links in Markdown is a
| PITA. Ditto good-looking tables. But still, the idea of "human-
| friendly-text-first" formats is valid.
|
| Doing the same for UML just makes sense to me.
|
| Now obviously there are implementation details I disagree with,
| both in the format and the renderer. But the idea is sound.
| matsemann wrote:
| These markup languages are often not competing with "making a
| single diagram with drag&drop", though. Lets say you're making
| lots of variations, then having it in a specified format for
| easy changes is nice. Or diffing changes. Or programmatically
| generate them.
| dagw wrote:
| _Lets say you 're making lots of variations, then having it
| in a specified format for easy changes is nice. Or diffing
| changes. Or programmatically generate them._
|
| But in all those cases wouldn't it better to have something
| with an actual API in a programming language you are familiar
| with? Or at least a tool the takes something like JSON, for
| which there already are great tools for parsing, generating
| and manipulating.
| withinboredom wrote:
| These specialized grammars attempt to strike a balance
| between human-readable and machine-readable. JSON is a
| terrible solution because you'd have to have an id +
| dictionary, then a list of relationships. Basically, no
| human is ever editing that.
| xdennis wrote:
| > Maybe it's not too bad for very simple diagrams but
| unmanageable for anything complex.
|
| Yeah, the problem with these sort of layout algorithms is that
| they don't have a sense of proportionality.
|
| I wonder if LLM can do this better. I've tried with 5 relations
| from this example one and ChatGPT comes up with this:
| Place "Jolly Sailor" at point (1, 1). Place "Pirate" at
| point (2, 1). Place "rum" at point (3, 2).
| Place "mischief" at point (2, 0). Place "Marauder" at
| point (3, 0).
|
| It looks okay, but I haven't checked with anything more
| complicated.
| thomasfromcdnjs wrote:
| Depends on the person I guess, I've actually found it easier to
| type out my diagrams.
| drivers99 wrote:
| I use graphviz dot (which is similar to this tool) specifically
| so I _don 't_ have to fight with getting the arrows right,
| manually fixing each one, in a visual editor.
| detectivestory wrote:
| I think this would work really well with the right vim plugin.
| fkyoureadthedoc wrote:
| I use mermaid sequence diagrams all the time and much prefer
| them to using whatever app. GitHub can render them which is
| nice. Refactoring them is easier than dragging 20 boxes around
| too in my opinion. I've done a couple Gantt charts. I see they
| support c4 which I need to try.
|
| We don't have many options of approved diagramming software
| where I work though. Omnigraffle which I don't care much for,
| and Visio which doesn't work on Mac. Maybe I'd have a different
| opinion of we had something proper.
|
| For random boxes and arrows I do typically go for Excalidraw
| though.
| Veuxdo wrote:
| Have you looked at Ilograph? It's diagrams-as-code that
| supports first-class sequence diagrams. E.g. https://app.ilog
| raph.com/demo.ilograph.Ilograph/Get%2520diag...
| candiddevmike wrote:
| I wish there was a way to easily export mermaid diagrams to
| PNG or PDF. Right now sharing the diagrams, especially ones
| that scroll, is a pain in the ass.
| klinquist wrote:
| Since GitHub renders mermaid, you could simply share a link
| to a gist.
| victorp13 wrote:
| You can export to PNG and other formats in the Mermaid
| editor https://mermaid.live/
| jasonjmcghee wrote:
| There is https://github.com/mermaid-js/mermaid-cli
| lmeyerov wrote:
| Mermaid for message sequence diagrams is amazing -- we
| recently added 'GPT for diagramming' support to Louie
| (conversational data & compute notebooks), and combining
| these rich DSLs with conversational AI & an interactive
| UI is a pretty cool & time-saving experience because it
| can bootstrap a lot
|
| Example from work where the original took 1-2 hours: http
| s://www.loom.com/share/aa388d49f28d471d89e3d8c048e9c0a0
|
| It's amazing to think where these will be even 6mo from
| now
| kordlessagain wrote:
| This could be rewritten to save locally or an endpoint you
| run: https://github.com/kordless/mitta-screenshot. The code
| is in background.js. Just fullscreen the graph then click
| the icon.
| Veuxdo wrote:
| On the other hand, sharing via images isn't good, because
| the recipient loses accessibility. Probably better to just
| share the original in most cases.
| WesolyKubeczek wrote:
| Probably needs some work on mobile -- went there on a phone and
| the diagram was drawn on top of the editor, making the latter
| unusable.
| pja wrote:
| That's just the nomnomml demo website - the text is editable so
| that you can see live updates in the rendered UML diagram.
|
| The underlying js library will render straight to an HTML
| canvas or to SVG from a Node.js program. You can run it from
| the command line if you want to.
| WesolyKubeczek wrote:
| I know it is editable, it's just inconvenient af to edit the
| text if the diagram is being drawn right over it.
| withinboredom wrote:
| you can move it out of the way.
| einpoklum wrote:
| How does this compare with graphviz, if I were to only create
| graph-node-like objects rather than tables and such?
| cdchn wrote:
| graphviz can create tables and you can create arrows to
| specific table cells.
| evolvingstuff wrote:
| I love Nomnoml. I have lately been using it to visualize
| hierarchical tag structures in a browser-based PKM project I am
| working on. I find it creates fairly clean layouts.
|
| Example:
|
| https://imgbox.com/9A1mDyNv
| kagevf wrote:
| Reminds me of graphviz :)
| jiehong wrote:
| Looks nice, and much nicer from plantuml class diagrams [0].
|
| [0]: https://plantuml.com/class-diagram
| h0l0cube wrote:
| Might be. But instead of another fragmentary standard can't we
| make the already reasonably supported one look better by
| default?
| cdchn wrote:
| Maybe theres an opportunity for, instead of Yet-Another-Text-
| To-Diagram-DSL we could make a diagram styling store ala
| WordPress themes.
| monkeydust wrote:
| Is this type of framework the future of email perhaps? For one I
| loathe long directionless emails and increasingly my mind starts
| wondering to something more structured to convey intentions and
| ideas - should add I am on the business side not an engineer.
| lcnPylGDnU4H9OF wrote:
| > something more structured to convey intentions and ideas
|
| I struggle to think of what this might be without it turning
| into some other natural language. For example, the tool that's
| used to convey intentions and ideas in these comments is
| written English, which certainly has its own structure.
| ademeure wrote:
| I made a few tools using nomnoml in the past, including control
| flow & dependency graphs for GPU assembly code. I really like it,
| the only negative was that there's no reliable way to push
| certain things to be positioned close together, so for extremely
| large diagrams it sometimes makes bad choices and it gets a bit
| messy.
|
| The code is reasonably easy to modify as well even if it isn't
| fully documented, so I was able to hack in a way to have tooltips
| on hover, and making certain boxes clickable linking to other
| diagrams. I'm really grateful for this awesome tool being open
| source!
___________________________________________________________________
(page generated 2023-10-02 23:01 UTC)