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

Nomnoml

nomnoml.com

Post reply on HN
Print view View original

121–130 of 165 posts

Re: Nomnoml

#121

Post by zoogeny »

ororroro wrote: post #38

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 ->[ e] [ start] -> [ plunder] -> [ more loot] -> [start] [Pirate| [foul mouth] mischief| bawl | sing || yell | drink ] [ Marauder] Jolly;Sailor] [sailor]->[rum] [Pirate]…

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.

Re: Nomnoml

#122

Post by lmeyerov »

jasonjmcghee wrote: post #118
candiddevmike wrote: post #85

Earlier quoted context omitted.

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.

There is https://github.com/mermaid-js/mermaid-cli

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: https://www.loom.com/share/aa388d49f28d471d89e3d8c048e9c0a0

It's amazing to think where these will be even 6mo from now

Re: Nomnoml

#123

Post by dingosity »

mactavish88 wrote: post #4

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.

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.

Re: Nomnoml

#124

Post by lelanthran »

zimpenfish wrote: post #43
PaulRobinson wrote: post #37

Earlier quoted context omitted.

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

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.

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

Re: Nomnoml

#125

Post by zeroxfe »

mactavish88 wrote: post #4

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.

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

Re: Nomnoml

#126

Post by budoso »

mactavish88 wrote: post #4

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.

Personally I think posting to Github is the offering part, posting the tool to HN is definitely an invitation for opinions.

Re: Nomnoml

#127

Post by sneak »

mactavish88 wrote: post #4

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.

Reading requests is not burdensome. It's just feedback.

Re: Nomnoml

#128

Post by BossingAround »

z500 wrote: post #95
CapsAdmin wrote: post #18

Earlier quoted context omitted.

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

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

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.

Re: Nomnoml

#129

Post by cjf101 »

saberience wrote: post #32

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.

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.

Re: Nomnoml

#130

Post by Cerium »

vekker wrote: post #31
sBqQu3U0wH wrote: post #27

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…

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

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.

Post reply on HN