Diagrams for Documentation

gistfile1.md

some tools for diagrams in software documentation

Diagrams For Documentation

Obvious Choices

• Graphviz
• Pandoc

ASCII

• AsciiFlow Editor online web-editor, limited shapes
• Ditaa Generator Java
• Ascidia Generator Python

UML

• Class Diagram - yUML
• Activity Diagram - yUML
• Use Case Diagram - yUML

yUML (ruby on rails) can be hosted yourself, for 49 USD

• Sequence Diagram - js-sequence-diagrams JavaScript, browser, SVG
• Sequence Diagram - flowchart.js JavaScript, browser, SVG

Sequence Diagrams

• KangaModeling, dot-like, web-api-renderer, .NET

• https://stackedit.io/

---

---

---

https://www.lucidchart.com/ via https://twitter.com/florian_st/status/502171491665211396
http://www.umlet.com/ via https://twitter.com/rauschma/status/502174264976769025
http://www.yworks.com/en/products_yed_about.html via https://twitter.com/ditman/status/502175301887983616

https://github.com/mdaines/viz.js/ via https://twitter.com/kaystrobach/status/502430401827459074

https://www.draw.io/ via https://twitter.com/hmitsch/status/503844939726614529

• TikZ and PGF. (if you're using LaTeX for docs) See http://www.texample.net/tikz/examples/ for examples.
• PlantUML: http://plantuml.sourceforge.net/
• Shaape: https://github.com/christiangoltz/shaape

Ditaa, Shaape, Graphviz and PlantUML are currently available to Asciidoctor via asciidoctor-diagram: http://asciidoctor.org/docs/asciidoctor-diagram/

At this point I think I'm going with yED (free, visio-like, looks powerful) (or another GUI application) and render images that are then embedded in markdown files. That means I don't see the benefit of ASCII based diagrams anymore - they look hard to maintain and only help in source-code-mode (which I'm definitely not optimizing for).

yED is great. The ascii-based ones, I would only ever use for very simple diagrams. That said, text-/relationship-based ones like PlantUML and Graphviz can be extremely useful since you're not so much drawing as "describing". And the crazy stuff TikZ can do knows no limits.

https://www.omnigroup.com/omnigraffle

I've been playing with Gliffy, simple but powerful enough for my needs.

Hello, I found this Gist and thought I'd add gravizo. If you're OK with the logo embed, they promise it will always remain free 🙃

So using one of the tools above, if you can get it to export a uml diagram then you can just embed that directly in your markdown doc :)

It takes some tinkering to get the styling, but an interesting option worthy of this excellent list!

I like Monodraw -- you can copy/paste into github markdown files and it renders nicely:

	┌──────────────────────────────────────────────────────────┐
	│                     Host OS (Linux)                      │
	│                                                          │
	│  ┌───────────────┐ ┌───────────────┐  ┌───────────────┐  │
	│  │ Container OS  │ │ Container OS  │  │ Container OS  │  │
	│  │   (Ubuntu)    │ │   (Ubuntu)    │  │   (Ubuntu)    │  │
	│  │ ┌───────────┐ │ │ ┌───────────┐ │  │ ┌───────────┐ │  │
	│  │ │ Couchbase │ │ │ │ Couchbase │ │  │ │ Couchbase │ │  │
	│  │ │  Server   │ │ │ │  Server   │ │  │ │  Server   │ │  │
	│  │ └───────────┘ │ │ └───────────┘ │  │ └───────────┘ │  │
	│  └───────────────┘ └───────────────┘  └───────────────┘  │
	└──────────────────────────────────────────────────────────┘

Thanks for recommending Monodraw. I am trying it right away.

+1 for Monodraw. Just bought a copy. Uber cool.

https://github.com/kbilsted/AsciiUml still very alpha at this stage though ;)

https://www.zenuml.com?ref=gist focuses on sequence and it comes with a chrome extension http://bit.ly/web-sequence-ws .Both the online version and the chrome extension work perfectly offline.

An online app to create sequence diagram that I use is websequencediagram. It's very useful for simple diagrams.

Hi, I need to help to star uml lesson. Can I help me this project.please shape Of urgently contact with me .
Please I took lesson star uml at University .But I need to help star uml .I need to obtain aproximately 5000 Code project .
my project will be date of delivery is may 13 finished. ,For this reason I have time is short .
Best wishes

https://shd101wyy.github.io/markdown-preview-enhanced/#/diagrams

This site https://sourcespy.com generates diagrams based on (java) source code you provide. You can modify diagrams as needed and use hosted pictures in your documentation. Something like this:

PlanUML project also allow you to build cool diagrams (Architecture, Sequence, Flow, etc..) using just a plain text format. You can use an online version here. Below an Architecture example with PlanUML definitions.

@startuml
rectangle "Services Flow Architecture" {
    rectangle "Services Examples" as Services {
      ["queue service server"] as qss
      ["queue service consumer"] as qsc
      ["queue worker"] as qw
      ["notifications"] as notify

      qss -[hidden]down-> qsc
      qsc -[hidden]down-> qw
      qw -[hidden]down-> notify
    }

    rectangle "AWS ActiveMQ" {
        queue "events queue" as eq
        queue "events topic" as et
    }
    qss -> eq
    qsc -> eq
    notify -> eq
    qw -> eq

    eq -up-> et
}

@enduml

I have attached a sample below.

What about https://mermaid-js.github.io/mermaid/#/?

I've been playing with Gliffy, simple but powerful enough for my needs.

Hello
I am working on asciidoctor-gradle-plugin and want to find a way how to edit existing or create new diagrams within asciidoctor in gradle. Is there a way to do this? Thank you in advance :D

https://shd101wyy.github.io/markdown-preview-enhanced/#/diagrams

https://github.com/yuzutech/kroki

You can also use diagrams.net (draw.io) diagrams in your repository. Check it out

Mermaid is Github native now.

  graph TD;
      A-->B;
      A-->C;
      B-->D;
      C-->D;

Loading

I'd forgotten the name, and found this Gist organically via Google. Seems like Mermaid is definitely worth mentioning here in this context. 😉