Looks pretty cool. I think it's great that you support light/dark mode. FWIWI, I'm also a huge fan of Excalidraw.
I wanted to ask you: is there's a reason you use a separate svg file for each (light/dark) mode?
A single SVG file using CSS can change it's own colors based on the user's preference. I have an example here: http://alejo.ch/3jj - the 3 plots should honor your mode (I put the generator code here: https://github.com/alefore/mini_svg)
Just figure I'd ask. If you have a good reason for using separate files, I'd love to hear it (because it probably would also apply to what I'm doing). :)
Edit: To expand on this, I dislike light/dark toggles. If I have dark mode on, seeing a bright screen and having to search for a toggle is jarring. Just show me the colours according to my preference!
Author here: I use mermaid lot as well and for some things like process flows, and to model interactions it it outrules excalidraw and posts will follow where i need exactly that. but to visualize things high level i find excalidraw way nicer.
I made a custom Payload CMS block that allows to create and update excalidraw diagrams within the CMS. It supports dark and light mode switching and rendering inline or as external SVG.
And last weekend I added MCP server with Oauth so I could generate and update those diagrams and add them to post drafts from Claude. I think it is more convenient since I don't have to use API billing model and don't need to build a custom UI.
Originally I wanted to sync posts from Obsidian but it doesn't have good enough image handling which I sometimes need and I needed extra metadata to unlist or password protect or noindex some posts.
I love excalidraw, but I have to agree. It also looks very unprofessional so if you ever have to write customer-facing diagrams, you have tool fragmentation. I just stick to draw.io now (aka diagrams.net)
Why does it cause tool fragmentation? You can change the font to a normal sans-serif font or to a monospaced font.
Personally I like the default font. It looks weird to have my crappy doodles next to a normal computer font. The default one is very legible but has a style (and ligatures) that make it feel not too neat
The Excalidraw website describes itself as: Excalidraw is a virtual collaborative whiteboard tool that lets you easily sketch diagrams that have a hand-drawn feel to them.
And the GitHub repo says: An open source virtual hand-drawn style whiteboard.
Collaborative and end-to-end encrypted.
I love diagramming, but I genuinely don't understand how people can use these wonky looking tools. It looks off, I had to make my own[1] to create something that's easy to use and looks good/normal.
I like the wonky, hand-drawn looking style. I think it fits well beause usually if I use a diagram it's not 100% precise and accurate, but more a high-level illustration. The wonky style conveys the approximate precision of the presented concept.
I agree 100% it's personal, wasn't trying to imply anything else, but for me the style takes away from the actual content and makes it harder to read/grasp.
Excalidraw has a 1 click 'sloppiness' change. We do drafts and ideation in 'full sloppy' mode, to indicate to the reader that this is not fully thought through, or a final documented decision. Once we've gotten through discussions and analysis, the final diagram is changed to be 'not sloppy', and the font changed from handwriting to a san serif font.
It's pretty effective to immediately communicate to folks that 'this is a concept' approach. Too many people instantly jump to conclusions about diagrams - if it's written down it must be done / fixed / formal.
Click the AI button in the toolbar to copy the Grafly format reference.
Paste it into any LLM (Claude, ChatGPT, Gemini…) along with a description of the diagram you want.
Copy the JSON the LLM returns.
Click the Import JSON button () in the toolbar and paste it in.
”
Super user friendly as well! I don’t even understand the instructions on how to use it.
In the upper right there is an import/export button that could be used for this. It's stored in localstorage so you could also dump that to wherever you like.
edit: added link to the repo in the about modal.
edit2: added import export of the entire localstorage entry on the bottom of the diagrams(left) panel.
I absolutely love it that you can import mermaid. I love mermaid because I'm a huge fan of anything related to code that can I check into git, track its evolution and the thinking that went behind it.
However, those who don't know mermaid have to struggle with updating my diagrams. Your approach, atleast in theory, should get us the best of both worlds. Mermaid for those who would like to and the mouse for those who don't.
This also addresses the issue that large complex diagrams can get unwieldy using Mermaid and moving things around with a mouse would fix those edge cases.
Depends on what you want to achieve with your look. Do you want to scream professionalism, authority, and completed?
Use a regular UML tool.
Want to say this is a rough draft of a few ideas? Then using UML is probably THE wrong look. And Exaclidraw should be used instead.
---
Anecdote time. According to one of my professors, they showed how the prototype will look in action, and the customers were so impressed by the smoke and mirrors prototype they wanted to start using it right away.
In the end, customer walked away because they thought they were being strung along to pay for something that was already done.
Wow, I had no idea that excalidraw could "import" mermaid!! This is just awesome.. I can have my LLM generate mermaid, which it is really very good at. And then I can edit the diagram!
You can also bootstrap your initial schema with LLMs with the excalidraw MCP "app" [0]. But MCP "apps"[1] are quite new and not very well supported yet.
I didn't have good experience with excalidraw-mcp when it first came out a month ago; the Claude-generated diagrams were too raw/unpolished. I'm sticking to mermaid for now but I'm interested in hearing how people make exclidraw-mcp work for them
Interesting approach. I make heavy use of Mermaid as I find it easier to make small changes and bulk generate-and-copy for publishing elsewhere. But being able to update the diagram and automatically generate the output files is a nice hybrid.
I have noticed diagrams are most useful early in thinking, but once things get complex they either become outdated or too hard to maintain. Curious how people here deal with that, do you keep diagrams in sync with code, or treat them as disposable?
I treat them as sketches, the way Martin Fowler used to describe a UML diagram. They have to be either disposable or treated as a notepad. I reconstruct the full picture only when it's necessary from "sketches". E.g., since Lucid has an infinite canvas, I'll put all my different diagrams on a single canvas, along with little diagrammatic "ideas", "notes", "brain-f$rts", etc.
For a presentation or project documentation artifacts, I can then go thru my sketches and pull bigger pictures together easily. I applied Fowler's "sketch" principle in my own tool ormle.com
I find I end up needing to walk the code to make diagrams of the current state anytime management wants to know what’s going on. It’s the only way my managers seem to understand or accept anything.
It’s a lot of work, as starting over is often easier than reviews and edits. Usually the diagrams are slightly out of date, but good enough to satisfy whoever is looking at it.
I wish I had a better solution. Now I’m wondering I could write something that walks the code for me.
Hey look, someone else has the exact same problem I do! I even use Excalidraw for diagramming as well, and have been wondering about how best to generate them according to some kind of binary format.
I have reverted to using mermaid where we are beyond the ideation phase. Then the mermaid code can live next to the document source, and I need not search for the original diagram file to edit and export. Confluence has a nice mermaid plugin.
Everyone does that these days and they are becoming AI tells like the em-dash or the blue-glow of the early AI generated images that everyone added to their blog posts.
AI can generate mermaid diagrams, not excalidraw. If you use the mermaid to excalidraw, i guess it can be, but it just looks like a mermaid diagram then and not an excalidraw.
I simply just draw in excalidraw and take a ss and past it in my obsidian note, I have a setup that automatically parses posts from my vault and then pushes them to my site
Protip: select the items in the canvas you want in your SS and 'copy to clipboard as PNG' instead of a screen shot and you can get transparent PNGs of diagrams or of detailed subsets of a larger diagram easily.
Same. I started using it for Gethly blog. It's not perfect, some things make me crazy but overall it is better than draw.io that I used to use before. Excalidraw also has these great styles that just feel right :)
I use Excalidraw extensively at work. For me, it's really close to perfection.
It has an excellent UI, selections work way better than Lucid or Figma etc, the sketchy look makes it clear designs are rough and not blueprints, it's private and loads instantly.
The one negative is that it's a pain to get the multiplayer self-hosted version running.
The company where I'm contracted retired Excalidraw in favor of Lucid and, while I understand that big companies are going to go with big, enterprise-y solutions, what went from a weekly "sketch something out to help with communicating my ideas" turned into "once every few months I begrudgingly document something".
Excalidraw is excellent for low-friction sketches.
Both Excalidraw and TLDraw are the two most popular apps of their kind, simplistic whiteboard tools, so I don't think it's that surprising and I don't see any reason why this post should be a "Show HN".
For me, draw.io is still the winner, and especially now that it runs locally also on Linux. As for works in progress, I hope this one succeeds (and would also run locally at some point):
I love excalidraw, but don't need the excalidraw+. But Excalidraw open source is the frontend only, which means I have to delete my drawings each time. So I built the backend so I can create many canvases.
Your site makes me make an account before I can use it, whereas excalidraw.com doesn't, and also excalidraw.com seems to save my drawing just fine? I closed a tab and reopened it and my drawing was still there, presumably from localStorage.
The three-lines-menu also has a "Save to..." option that lets you create a sharable link or save to your local disk.
Hey, I found that interesting and went looking for an RSS feed link on your site but couldn't find any. Assuming you don't have it already, do you plan to add it?
Documentation often rots away because it's often decoupled from the code it describes.
I'm a huge fan of anything related to code that can I check into git, track its evolution and the thinking that went behind it. Why was Kubernetes chosen? Why was NATs chosen? Why are the topics named the way they are?
I am a huge fan of mermaid diagrams because it lets me check in my diagrams into git. I am a huge fan of mermaid diagrams because my code can generate diagrams that I (or they) can check into git - and this was before AI.
Now that AI can generate mermaid diagrams, people look at my Git repos and go "oh, you use AI a lot!" - then I point to my git history and they see it's from 2018.
I'm really happy that mermaid and related tools like Excalidraw are taking off - we have another chance at documentation being automated, uptodate and "fresh".
Love Excalidraw. Used it for decades now, but reach for more powerful tools pretty often as I hit its limits. I'm not asking for the world, but some basics like being able to bold or italicize text would help out a lot.
YES YES YES! Excalidraw is amazing, I recently embedded it into my vibe coded project to add version control integration with it. Honestly one of highest quality tools I've used for my workflow, does what it needs to do and doesn't get in your way.
I've always liked umlet and umletino (web version) for a nice mix of drag and drop and edit by text editor. In the absence of good enough layout algorithms, the ability to manually drag things to the right place is kind of essential. The resulting diagrams are not so pretty of course.
I have tried a lot of tools in this space. If it comes out looking alright, that's usually because it was so simple that it didn't actually need a diagram. Anything with a bit of non trivial structure seems to quickly escalate with essentially no good options other then esoteric hacks with styling to make it look any good.
This seems to be a thing where you can have pretty automated layouts, complex diagrams, or correct diagrams and can only have two out of three.
Which means that almost 100% of my use cases for these tools never really work for me unless I sit down and grab some old school drawing tool (or just give up on the whole notion, which is much more likely). If it was trivial, I wouldn't bother making a diagram. These tools seem only usable for stuff where diagrams were overkill to begin with. I saw no examples on the linked article (and the rest of the site; I browsed the top few recent articles) to really counter this.
Looks pretty cool. I think it's great that you support light/dark mode. FWIWI, I'm also a huge fan of Excalidraw.
I wanted to ask you: is there's a reason you use a separate svg file for each (light/dark) mode?
A single SVG file using CSS can change it's own colors based on the user's preference. I have an example here: http://alejo.ch/3jj - the 3 plots should honor your mode (I put the generator code here: https://github.com/alefore/mini_svg)
Just figure I'd ask. If you have a good reason for using separate files, I'd love to hear it (because it probably would also apply to what I'm doing). :)
My goal is that it renders on GitHub as well as on my blog. GitHub doesn’t support css based dark mode afaik
Ah, you have a button for the toggle! Did you know that you can conform to the user's light/dark preference with CSS? Like this:
Edit: To expand on this, I dislike light/dark toggles. If I have dark mode on, seeing a bright screen and having to search for a toggle is jarring. Just show me the colours according to my preference!Huge fan of https://github.com/mermaid-js/mermaid, not the prettiest things but enough to scratch the itch.
Author here: I use mermaid lot as well and for some things like process flows, and to model interactions it it outrules excalidraw and posts will follow where i need exactly that. but to visualize things high level i find excalidraw way nicer.
Cool, I did a similar thing last week.
I made a custom Payload CMS block that allows to create and update excalidraw diagrams within the CMS. It supports dark and light mode switching and rendering inline or as external SVG.
And last weekend I added MCP server with Oauth so I could generate and update those diagrams and add them to post drafts from Claude. I think it is more convenient since I don't have to use API billing model and don't need to build a custom UI.
Here is an example post: https://www.janhouse.lv/blog/network/self-hosting-tailscale-...
Originally I wanted to sync posts from Obsidian but it doesn't have good enough image handling which I sometimes need and I needed extra metadata to unlist or password protect or noindex some posts.
It would have been great if Excalidraw made it easier to do manage multiple scenes. I use its PWA and save individual files on the disk.
I thought about forking the pwa - should be easy to add the same concept using https://developer.chrome.com/docs/capabilities/web-apis/file... but I didn't want to leave vscode
Excalidraw has proliferated quite widely in my company since we got Claude Code. Its a shame the default font is ugly, childish and inaccessible.
I love excalidraw, but I have to agree. It also looks very unprofessional so if you ever have to write customer-facing diagrams, you have tool fragmentation. I just stick to draw.io now (aka diagrams.net)
Why does it cause tool fragmentation? You can change the font to a normal sans-serif font or to a monospaced font.
Personally I like the default font. It looks weird to have my crappy doodles next to a normal computer font. The default one is very legible but has a style (and ligatures) that make it feel not too neat
Whiteboard handwriting is childish?
It's not on a whiteboard, nor was it written by hand. It's a computer font.
The Excalidraw website describes itself as: Excalidraw is a virtual collaborative whiteboard tool that lets you easily sketch diagrams that have a hand-drawn feel to them.
And the GitHub repo says: An open source virtual hand-drawn style whiteboard. Collaborative and end-to-end encrypted.
It's the intended design...
Cool. I have stated my opinions on their intended design.
Cool. I have stated the facts of the product.
It just looks weird not childish.
I love diagramming, but I genuinely don't understand how people can use these wonky looking tools. It looks off, I had to make my own[1] to create something that's easy to use and looks good/normal.
[1] https://grafly.io
I like the wonky, hand-drawn looking style. I think it fits well beause usually if I use a diagram it's not 100% precise and accurate, but more a high-level illustration. The wonky style conveys the approximate precision of the presented concept.
Also, and that's personal, I think it's cute.
I agree with you. I think the 'wonky' comment was more to serve as justification for the plug than an actual criticism of Excalidraw.
Excalidraw is my favourite thinking tool, and the style it produces is just the right level of limiting, disarming, and professional at the same time.
It's not, I genuinely find it harder to read diagrams. And also the plug is very relevant, I wanted to share, it's not a saas it's a free tool.
I agree 100% it's personal, wasn't trying to imply anything else, but for me the style takes away from the actual content and makes it harder to read/grasp.
I thought they were saying the tool is wonky looking, but <shrug>?
One person's bug is another's feature.
Excalidraw has a 1 click 'sloppiness' change. We do drafts and ideation in 'full sloppy' mode, to indicate to the reader that this is not fully thought through, or a final documented decision. Once we've gotten through discussions and analysis, the final diagram is changed to be 'not sloppy', and the font changed from handwriting to a san serif font.
It's pretty effective to immediately communicate to folks that 'this is a concept' approach. Too many people instantly jump to conclusions about diagrams - if it's written down it must be done / fixed / formal.
In Excalidraw, you can reduce (and completely remove) the "sloppiness" in the element properties.
“USING AI TO GENERATE DIAGRAMS
Click the AI button in the toolbar to copy the Grafly format reference. Paste it into any LLM (Claude, ChatGPT, Gemini…) along with a description of the diagram you want. Copy the JSON the LLM returns. Click the Import JSON button () in the toolbar and paste it in. ”
Super user friendly as well! I don’t even understand the instructions on how to use it.
This looks really clean, nice work. I’ve had the same issues with most diagramming tools, it's either not so good looking or the insane pricing .
I went a different route using diagram-as-code with Mermaid instead of manual drawing.
[1] https://graphlet.xyz
Thanks! I love Mermaid as well, I made it so you can import Mermaid diagrams as well.
The best way to drive adoption to your product is to not shit on someone else's labour of love. Just a little pro-tip.
How did I shit on excalidraw? I don't like how it looks, it's a personal preference. I don't think saying that equates to shitting on it.
Whimsical is a whiteboard/diagram app that I think looks pretty nice, not too far from how yours looks
Questions:
1. Will you be making the source code public?
2. How to export the JSON for SCM, then re-import for updating/maintenance?
It's open source, I just haven't linked it in the project (my bad).
https://github.com/lnenad/grafly/
In the upper right there is an import/export button that could be used for this. It's stored in localstorage so you could also dump that to wherever you like.
edit: added link to the repo in the about modal. edit2: added import export of the entire localstorage entry on the bottom of the diagrams(left) panel.
I absolutely love it that you can import mermaid. I love mermaid because I'm a huge fan of anything related to code that can I check into git, track its evolution and the thinking that went behind it.
However, those who don't know mermaid have to struggle with updating my diagrams. Your approach, atleast in theory, should get us the best of both worlds. Mermaid for those who would like to and the mouse for those who don't.
This also addresses the issue that large complex diagrams can get unwieldy using Mermaid and moving things around with a mouse would fix those edge cases.
> It looks off
Depends on what you want to achieve with your look. Do you want to scream professionalism, authority, and completed? Use a regular UML tool.
Want to say this is a rough draft of a few ideas? Then using UML is probably THE wrong look. And Exaclidraw should be used instead.
--- Anecdote time. According to one of my professors, they showed how the prototype will look in action, and the customers were so impressed by the smoke and mirrors prototype they wanted to start using it right away.
In the end, customer walked away because they thought they were being strung along to pay for something that was already done.
When a background shape is in focus it comes to the foreground covering the shapes that are on top of it.
That is by design. If you deselect it it goes back to it's layer.
https://news.ycombinator.com/item?id=47503348
I prefer excalidraw …
looks awesome man !
Wow, I had no idea that excalidraw could "import" mermaid!! This is just awesome.. I can have my LLM generate mermaid, which it is really very good at. And then I can edit the diagram!
You can also bootstrap your initial schema with LLMs with the excalidraw MCP "app" [0]. But MCP "apps"[1] are quite new and not very well supported yet.
[0] -- https://github.com/excalidraw/excalidraw-mcp
[1] -- https://modelcontextprotocol.io/extensions/apps/overview
I didn't have good experience with excalidraw-mcp when it first came out a month ago; the Claude-generated diagrams were too raw/unpolished. I'm sticking to mermaid for now but I'm interested in hearing how people make exclidraw-mcp work for them
Interesting approach. I make heavy use of Mermaid as I find it easier to make small changes and bulk generate-and-copy for publishing elsewhere. But being able to update the diagram and automatically generate the output files is a nice hybrid.
I use Mermaid too, but a lot of that comes down to the fact that it's easier to generate it with Claude.
It can be exceedingly useful to do this if you have a big log file and you need to have a diagram of a trace, even if you're not sharing it on a blog.
That fits perfectly with the idea that everything should actually be in the repository. At last, I no longer have to update the images myself. Thanks!
Thanks for the flowers
And I'm over here using Graphviz like some caveman.
I have noticed diagrams are most useful early in thinking, but once things get complex they either become outdated or too hard to maintain. Curious how people here deal with that, do you keep diagrams in sync with code, or treat them as disposable?
I treat them as sketches, the way Martin Fowler used to describe a UML diagram. They have to be either disposable or treated as a notepad. I reconstruct the full picture only when it's necessary from "sketches". E.g., since Lucid has an infinite canvas, I'll put all my different diagrams on a single canvas, along with little diagrammatic "ideas", "notes", "brain-f$rts", etc.
For a presentation or project documentation artifacts, I can then go thru my sketches and pull bigger pictures together easily. I applied Fowler's "sketch" principle in my own tool ormle.com
I find I end up needing to walk the code to make diagrams of the current state anytime management wants to know what’s going on. It’s the only way my managers seem to understand or accept anything.
It’s a lot of work, as starting over is often easier than reviews and edits. Usually the diagrams are slightly out of date, but good enough to satisfy whoever is looking at it.
I wish I had a better solution. Now I’m wondering I could write something that walks the code for me.
Hey look, someone else has the exact same problem I do! I even use Excalidraw for diagramming as well, and have been wondering about how best to generate them according to some kind of binary format.
I have reverted to using mermaid where we are beyond the ideation phase. Then the mermaid code can live next to the document source, and I need not search for the original diagram file to edit and export. Confluence has a nice mermaid plugin.
That way, the diagram source and
My approach:
Do use diagrams to explain an abstraction, and attach a word to it. Don't use diagrams to represent the exact state of a system.
Everyone does that these days and they are becoming AI tells like the em-dash or the blue-glow of the early AI generated images that everyone added to their blog posts.
AI can generate mermaid diagrams, not excalidraw. If you use the mermaid to excalidraw, i guess it can be, but it just looks like a mermaid diagram then and not an excalidraw.
PlantUML is a better ask for LLMs, you have a lot more control over the output
100% agree
https://claude.com/connectors/excalidraw-app-demo
we have an excalidraw MCP for claude, it can easily do both :) (Excalidraw is basically just fancy SVG)
oh wow, cool
I simply just draw in excalidraw and take a ss and past it in my obsidian note, I have a setup that automatically parses posts from my vault and then pushes them to my site
I use the Obsidian Excalidraw plugin, means I can add diagrams to notes without leaving Obsidian.
Yeah I use that plugin too. I was just referencing it in relation to how I setup my blog[1]
[1]: https://darshanmakwana412.github.io/2026/03/a-system-of-jour...
Protip: select the items in the canvas you want in your SS and 'copy to clipboard as PNG' instead of a screen shot and you can get transparent PNGs of diagrams or of detailed subsets of a larger diagram easily.
Obsidian also offers a full excalidraw integration
Not what I needed - my concepts life in one excalidraw, containing multiple frames of interest like https://github.com/martin-lysk/martin-lysk/blob/main/blog/26.... The blogposts reference some of them like here: https://blog.lysk.tech/nfs3-event-side-channel
Great article, should make sure to attribute xkcd comics though.
https://xkcd.com/about/
Thanks for the hint - just updated the post and adde the attribution
Same. I started using it for Gethly blog. It's not perfect, some things make me crazy but overall it is better than draw.io that I used to use before. Excalidraw also has these great styles that just feel right :)
Should be Show HN.
Now it reads like an ad for some extension to a program I've never heard about.
Apparently Excalidraw is An open source virtual hand-drawn style whiteboard. Collaborative and end-to-end encrypted.
https://github.com/excalidraw/excalidraw
I use Excalidraw extensively at work. For me, it's really close to perfection.
It has an excellent UI, selections work way better than Lucid or Figma etc, the sketchy look makes it clear designs are rough and not blueprints, it's private and loads instantly.
The one negative is that it's a pain to get the multiplayer self-hosted version running.
The company where I'm contracted retired Excalidraw in favor of Lucid and, while I understand that big companies are going to go with big, enterprise-y solutions, what went from a weekly "sketch something out to help with communicating my ideas" turned into "once every few months I begrudgingly document something".
Excalidraw is excellent for low-friction sketches.
My favorite aspect of it is the keyboard shortcuts. It makes things so much faster.
I was surprised about that, too. Tried a bit but found very few sources online.
A self-hosted version with storage (multiplayer) plus any Claude access would be a killer setup for team planning etc and let us drop Miro.
Both Excalidraw and TLDraw are the two most popular apps of their kind, simplistic whiteboard tools, so I don't think it's that surprising and I don't see any reason why this post should be a "Show HN".
TLDraw: https://www.tldraw.com/
Excalidraw: https://excalidraw.com/
For me, draw.io is still the winner, and especially now that it runs locally also on Linux. As for works in progress, I hope this one succeeds (and would also run locally at some point):
TikzMaker: https://tikzmaker.com/
I love excalidraw, but don't need the excalidraw+. But Excalidraw open source is the frontend only, which means I have to delete my drawings each time. So I built the backend so I can create many canvases.
https://drawx.ossy.dev
I actually created a completely free chrome extension exactly for that reason helps you to save and open the files at excalidraw
https://github.com/AykutSarac/excalihub
Your site makes me make an account before I can use it, whereas excalidraw.com doesn't, and also excalidraw.com seems to save my drawing just fine? I closed a tab and reopened it and my drawing was still there, presumably from localStorage.
The three-lines-menu also has a "Save to..." option that lets you create a sharable link or save to your local disk.
You can also embed the excalidraw drawing in the exported image. So you can drag/drop the exorted image back into excalidraw and edit it later.
Pretty new to hn, thanks for the hint
I want to write a blog whose posts will be all about the technical details of how the blog works.
Author here: Haha - yeah that is kind of meta - i know. Other content will be more about the acutual problems i solve. Check out https://blog.lysk.tech/sqlite-on-git-prologue ;-)
Hey, I found that interesting and went looking for an RSS feed link on your site but couldn't find any. Assuming you don't have it already, do you plan to add it?
on it
https://blog.lysk.tech/rss.xml
Documentation often rots away because it's often decoupled from the code it describes.
I'm a huge fan of anything related to code that can I check into git, track its evolution and the thinking that went behind it. Why was Kubernetes chosen? Why was NATs chosen? Why are the topics named the way they are?
I am a huge fan of mermaid diagrams because it lets me check in my diagrams into git. I am a huge fan of mermaid diagrams because my code can generate diagrams that I (or they) can check into git - and this was before AI.
Now that AI can generate mermaid diagrams, people look at my Git repos and go "oh, you use AI a lot!" - then I point to my git history and they see it's from 2018.
I'm really happy that mermaid and related tools like Excalidraw are taking off - we have another chance at documentation being automated, uptodate and "fresh".
Love Excalidraw. Used it for decades now, but reach for more powerful tools pretty often as I hit its limits. I'm not asking for the world, but some basics like being able to bold or italicize text would help out a lot.
Decades? Wasn't it created in 2020?
YES YES YES! Excalidraw is amazing, I recently embedded it into my vibe coded project to add version control integration with it. Honestly one of highest quality tools I've used for my workflow, does what it needs to do and doesn't get in your way.
Another option I use open is to ask the code-agent to make a diagram using Tikz (as a .tex file), which can then be converted to pdf/png.
But in general AI-diagramming is still unsolved; needs several iterations to get rid of wonky/wrong arrows, misplaced boxes, misplaced text etc.
I've always liked umlet and umletino (web version) for a nice mix of drag and drop and edit by text editor. In the absence of good enough layout algorithms, the ability to manually drag things to the right place is kind of essential. The resulting diagrams are not so pretty of course.
I have tried a lot of tools in this space. If it comes out looking alright, that's usually because it was so simple that it didn't actually need a diagram. Anything with a bit of non trivial structure seems to quickly escalate with essentially no good options other then esoteric hacks with styling to make it look any good.
This seems to be a thing where you can have pretty automated layouts, complex diagrams, or correct diagrams and can only have two out of three.
Which means that almost 100% of my use cases for these tools never really work for me unless I sit down and grab some old school drawing tool (or just give up on the whole notion, which is much more likely). If it was trivial, I wouldn't bother making a diagram. These tools seem only usable for stuff where diagrams were overkill to begin with. I saw no examples on the linked article (and the rest of the site; I browsed the top few recent articles) to really counter this.
nice one!
Uh, that’s a nice approach.