5 ms·

Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are

Having fallen back in love with PlantUML recently I’ll never use a proprietary tool that doesn’t have declarative syntax. System diagrams and documentation are a crucial part of any software business and one that is regularly out of date as people end up using tools like draw.io which nobody knows how to get access to or use.

Veuxdo 5y ago
+1 for declarative syntax. Diagrams-as-code is great, but diagramming in a programming language (e.g. Python) is... weird.
- jasau 5y ago
  Just mentioning that programming language doesn't rule out the option to have declarative syntax for an API.
drewpc 5y ago
> I’ll never use a proprietary tool that doesn’t have declarative syntax Can you provide an example of what you're referring to?
- petepete 5y ago
  PlantUML diagrams are generated from plain text, they can easily be embedded in markdown or even in code (I'm sure there's a plug-in for that!) Plenty of examples here. https://plantuml.com/state-diagram https://plantuml.com/state-diagram
  - gregmac 5y ago
    And importantly, because they're text, they can live in a version-controlled environment. I mainly use them within Confluence, and even there you can diff between versions to see changes.
mattm 5y ago
Wow, this is interesting. Are there any diagramming tools that allow importing PlantUML to display them a little nicer than the examples?
- sombremesa 5y ago
  There’s some nicer looking ones here: https://crashedmind.github.io/PlantUMLHitchhikersGuide/ https://crashedmind.github.io/PlantUMLHitchhikersGuide/
iso1210 5y ago
How do people not know how to get or use draw.io? You literally go to draw.io and can use it online. We're replaced our diagramming with it instead of things like omnigraffle as it means everyone has access to tweak the diagrams without having to buy software (and then buy upgrades and plugins), and by embedding the diagram in the .png there's just one file to keep track of.
- deanclatworthy 5y ago
  I've worked at places where people have exported draw.io as PNG/PDF on internal wikis for diagrams. But what happens when you want to change it? You then have to track down the people who made them, and get access yourself - or find it buried on someone's google drive. With PlantUML you usually commit your diagram's text syntax to VCS, often close to the code. As far as usability, we're never going to agree. I find it tedious, compared to writing predictable declarative syntax.
  - iso1210 5y ago
    drawio embeds the code in the png, so you just edit it in situ.
    - john-tells-all 5y ago
      Wait, drawio embeds the source and rendered version in the same file? That's great! Here's more info => https://joe.blog.freemansoft.com/2020/10/diagram-definition-and-image-in-one.html https://joe.blog.freemansoft.com/2020/10/diagram-definition-...
- mroche 5y ago
  You can also use it offline, there's a downloadable Electron app they provide (AppImage on Linux). The shapes libraries are pretty nifty and extensive (just need to turn them on).

Veuxdo 5y ago

+1 for declarative syntax. Diagrams-as-code is great, but diagramming in a programming language (e.g. Python) is... weird.

jasau 5y ago
Just mentioning that programming language doesn't rule out the option to have declarative syntax for an API.

drewpc 5y ago

> I’ll never use a proprietary tool that doesn’t have declarative syntax Can you provide an example of what you're referring to?

petepete 5y ago
PlantUML diagrams are generated from plain text, they can easily be embedded in markdown or even in code (I'm sure there's a plug-in for that!) Plenty of examples here. https://plantuml.com/state-diagram https://plantuml.com/state-diagram
- gregmac 5y ago
  And importantly, because they're text, they can live in a version-controlled environment. I mainly use them within Confluence, and even there you can diff between versions to see changes.

mattm 5y ago

Wow, this is interesting. Are there any diagramming tools that allow importing PlantUML to display them a little nicer than the examples?

sombremesa 5y ago
There’s some nicer looking ones here: https://crashedmind.github.io/PlantUMLHitchhikersGuide/ https://crashedmind.github.io/PlantUMLHitchhikersGuide/

iso1210 5y ago

How do people not know how to get or use draw.io? You literally go to draw.io and can use it online. We're replaced our diagramming with it instead of things like omnigraffle as it means everyone has access to tweak the diagrams without having to buy software (and then buy upgrades and plugins), and by embedding the diagram in the .png there's just one file to keep track of.

deanclatworthy 5y ago
I've worked at places where people have exported draw.io as PNG/PDF on internal wikis for diagrams. But what happens when you want to change it? You then have to track down the people who made them, and get access yourself - or find it buried on someone's google drive. With PlantUML you usually commit your diagram's text syntax to VCS, often close to the code. As far as usability, we're never going to agree. I find it tedious, compared to writing predictable declarative syntax.
- iso1210 5y ago
  drawio embeds the code in the png, so you just edit it in situ.
  - john-tells-all 5y ago
    Wait, drawio embeds the source and rendered version in the same file? That's great! Here's more info => https://joe.blog.freemansoft.com/2020/10/diagram-definition-and-image-in-one.html https://joe.blog.freemansoft.com/2020/10/diagram-definition-...
mroche 5y ago
You can also use it offline, there's a downloadable Electron app they provide (AppImage on Linux). The shapes libraries are pretty nifty and extensive (just need to turn them on).