Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
Diagrams for Documentation

some tools for diagrams in software documentation

Diagrams For Documentation

Obvious Choices

ASCII

UML

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

Sequence Diagrams


Example Diagram


Dalek Class Dalek Sequence


@stephenhay
Copy link

stephenhay commented Aug 20, 2014

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

@rodneyrehm
Copy link
Author

rodneyrehm commented Aug 20, 2014

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).

@stephenhay
Copy link

stephenhay commented Aug 20, 2014

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.

@rodneyrehm
Copy link
Author

rodneyrehm commented Aug 21, 2014

@lloydwatkin
Copy link

lloydwatkin commented Aug 25, 2014

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

@svenevs
Copy link

svenevs commented Feb 5, 2017

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!

@tleyden
Copy link

tleyden commented Jul 13, 2017

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   β”‚ β”‚  β”‚
	β”‚  β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚  β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚  β”‚
	β”‚  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜  β”‚
	β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

@nvictor
Copy link

nvictor commented Aug 21, 2017

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

@prodrammer
Copy link

prodrammer commented Sep 10, 2017

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

@kbilsted
Copy link

kbilsted commented Oct 3, 2017

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

@MrCoder
Copy link

MrCoder commented Oct 23, 2017

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.

sample-30s 36ad6e1

@fgriberi
Copy link

fgriberi commented Feb 18, 2018

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

websequencediagram

@Buket-12
Copy link

Buket-12 commented Apr 28, 2018

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

@alexkarezin
Copy link

alexkarezin commented Aug 15, 2019

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:

@sbz
Copy link

sbz commented Nov 14, 2019

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.

image

@z0r1k
Copy link

z0r1k commented Feb 12, 2020

@pirancaci
Copy link

pirancaci commented Apr 7, 2020

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

@SamuelMarks
Copy link

SamuelMarks commented Jun 28, 2021

@philip-gai
Copy link

philip-gai commented Sep 29, 2021

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

@djmetzle
Copy link

djmetzle commented Mar 22, 2022

Mermaid is Github native now.

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

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment