3 ms·

Diagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.

by xamde 7y ago

gregmac 7y ago
I've included plantuml stuff in our internal documentation at work for a long time, and have got a lot of complements from people on how great our documentation is. I attribute a lot of this to the diagrams (mostly component and sequence diagrams), many of which are there just because of how simple and fast it is to create+maintain them with inline plantuml. Benefits: Fairly easy to learn syntax, and powerful enough for most technical documentation needs. Easy to edit, easy to consume. No launching some heavy desktop app, no worrying about keeping PNG+source files up to date. (I do often use liveuml.com for editing any non-trivial diagrams though.) Works with version control Consistent style even when different people are working on diagrams Drawbacks: Not that pretty. Someone even mildly proficient at PowerPoint can make better-looking diagrams (though it takes longer). If you're doing internal or technical docs this isn't worth it, but for marketing/end-user facing stuff, maybe. I'll often just give my plantuml diagram to marketing and let them have a graphic designer pretty it up. Less intuitive. The learning curve is a bit of a barrier for people that have spent years doing stuff in PowerPoint, and haven't yet bought into the other benefits. Especially for a simple diagram, it's hard to convince them to spend a couple hours so they can learn how to build it in 5-10 minutes with plantuml, vs just spending 10 minutes in PowerPoint. I think this is exacerbated by the fact a lot of the benefits come later when trying to edit and it gets more complex.
yoz-y 7y ago
PlantUML syntax is also a lot easier to maintain and update than an ascii chart which is basically a low res pixel art.
svnpenn 7y ago
Have you run into this? https://github.com/asciidoctor/asciidoctor/issues/1087 https://github.com/asciidoctor/asciidoctor/issues/1087 I love all the features of asciidoc but it bothers me they can't get the actual HTML generation right.

Diagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.

by xamde 7y ago

Diagrams with PlantUML in AsciiDoc are quite efficient. Faster than powerpoint.

I've included plantuml stuff in our internal documentation at work for a long time, and have got a lot of complements from people on how great our documentation is. I attribute a lot of this to the diagrams (mostly component and sequence diagrams), many of which are there just because of how simple and fast it is to create+maintain them with inline plantuml. Benefits: Fairly easy to learn syntax, and powerful enough for most technical documentation needs. Easy to edit, easy to consume. No launching some heavy desktop app, no worrying about keeping PNG+source files up to date. (I do often use liveuml.com for editing any non-trivial diagrams though.) Works with version control Consistent style even when different people are working on diagrams Drawbacks: Not that pretty. Someone even mildly proficient at PowerPoint can make better-looking diagrams (though it takes longer). If you're doing internal or technical docs this isn't worth it, but for marketing/end-user facing stuff, maybe. I'll often just give my plantuml diagram to marketing and let them have a graphic designer pretty it up. Less intuitive. The learning curve is a bit of a barrier for people that have spent years doing stuff in PowerPoint, and haven't yet bought into the other benefits. Especially for a simple diagram, it's hard to convince them to spend a couple hours so they can learn how to build it in 5-10 minutes with plantuml, vs just spending 10 minutes in PowerPoint. I think this is exacerbated by the fact a lot of the benefits come later when trying to edit and it gets more complex.

yoz-y 7y ago

PlantUML syntax is also a lot easier to maintain and update than an ascii chart which is basically a low res pixel art.

svnpenn 7y ago

Have you run into this? https://github.com/asciidoctor/asciidoctor/issues/1087 https://github.com/asciidoctor/asciidoctor/issues/1087 I love all the features of asciidoc but it bothers me they can't get the actual HTML generation right.