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

This comment has been minimized.

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

This comment has been minimized.

Copy link
Owner 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

This comment has been minimized.

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

This comment has been minimized.

Copy link
Owner Author

rodneyrehm commented Aug 21, 2014

@lloydwatkin

This comment has been minimized.

Copy link

lloydwatkin commented Aug 25, 2014

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

@svenevs

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

Copy link

nvictor commented Aug 21, 2017

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

@ryanhaney

This comment has been minimized.

Copy link

ryanhaney commented Sep 10, 2017

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

@kbilsted

This comment has been minimized.

Copy link

kbilsted commented Oct 3, 2017

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

@MrCoder

This comment has been minimized.

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

This comment has been minimized.

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

This comment has been minimized.

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

@sirianni

This comment has been minimized.

@alexkarezin

This comment has been minimized.

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

This comment has been minimized.

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.