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.)
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:
Different arrows are useful to express different relationships. But perhaps you should just put a legend next to each diagram, or use words to annotate your arrows?
No one forces you to use all possible arrows, you can learn just one, and use that.
When reading a diagram, ideally you would read it by looking at the generated diagram, not text, as that's the entire point, but even when reading the raw text, it's apparent where the arrows are, based on "less than" and "greater than" characters, no?
> 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.
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.
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.
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.
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.
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.
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.
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.
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!
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
> 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.
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.
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.
If you edit these manually - yes.
Usually these sort of tools are meant to generate output programmatically.
Otherwise dragn'drop could be more useful.
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.
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.
> 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 :)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
> 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.
>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.
> 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.
> 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?
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.
The issue with graph engines that manage the layout themselves is that it becomes very messy the higher the number of nodes you have. I've experienced this with Mermaid.js and Obsidian.
Still, I'd rather have textual hints about layout than explicit drag-and-drop. Stuff like "boxes a1, a2, a3 should be presented sequentially" or "box b1, b2, b3 are tightly related and should be presented close to each other" and "box c is the root of its tree" and stuff like that.
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.
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.
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.
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
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.
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.
> 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.
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.
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.
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.
> 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.
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.
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.
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)
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
> 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.
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
“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.
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.
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.
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.
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.
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.
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.
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.
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.
> 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.
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.
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.
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.
> 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.
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.
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.
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.
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.
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.
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.
I figure there's bound to be a parser in Python that can load my graphviz files and from there it's easy enough to transform objects in memory as required.
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
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.
I use mermaidjs for basically everything documentation related. It works in GitHub ... confluence ... everywhere. This looks like a much prettier version of that.
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).
