Skip to content

Instantly share code, notes, and snippets.

@rodneyrehm
Last active November 7, 2022 09:11
Show Gist options
  • Save rodneyrehm/40e7946c0cff68a31cea to your computer and use it in GitHub Desktop.
Save rodneyrehm/40e7946c0cff68a31cea to your computer and use it in GitHub Desktop.
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

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

@rodneyrehm
Copy link
Author

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

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

@lloydwatkin
Copy link

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

+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

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

websequencediagram

@Buket-12
Copy link

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

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

@philip-gai
Copy link

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