Block Diagram All the Things

[ericdmoore]

I think in Block Diagrams.
Let's assume that others don't hate the option of looking at block diagrams.

Start with:

• Spectapular Architecture
• Reporter Architecture
• Summarizer Architecture

Start By Exploring:

• Good Ways to incorporate block diagrams into source code
• Good Ways to reference the block diagrams
  • Embed in a reference document && ref the document? (Seems like a good start)
  • Embedable/collapseable/expandable diagram to be "imported" into every document?
  • How does versioning a diagram work?
  • How do projects handle syncing the diagram with the source code?
  • What are projects with good diagrams incorporated into the documentation?

[ericdmoore]

Out there I found:

• mermaid [MIT]
  • steep learning curve on mermaid's DSL
  • adds build step to docs
  • exportable files as vector or bitmaps
  • possible but hard to generate the mermaid DSL from the source code
  • likely opt for a diagram literate code style before endeavoring to lex the code base
  • turns out this is a wrapper on D3 already.

• D3JS [BSD-3]
  • Needs more consideration (WIP)
  • also steep learning curve
  • code would be writing the diagrams
  • I have not spent enough time with D3 code to find it as readable as you would want the fallback case for a diagram.

• JS Sequence Diagrams[BSD-2]
  • Needs more consideration (WIP)

• Railroad Diagram Generator [??]
  • Needs more consideration (WIP)

• Google Docs Diagrams [ ⚠️ 🔐 ]
  • free / easy / proprietary
  • manual syncing the diagram
  • look at the API to potentially autoexport the SVGs etc during a document build step

• Sketch App [💸 💸 ]
  • great app but proprietary
  • manual syncing (export SVG files)docs and source code

• Yuml.me [💸 💸 ]
  • Needs more consideration (WIP)

• Creately [💸 💸 ]
  • Needs more consideration (WIP)

• Other Options?

[ericdmoore]

Crazy idea:
Host the mermaid (or similar) runtime in an API the returns SVG.

That would result in npm shields but for diagrams. WOOO HOO!

🚀🔗 ♦️♦️⬛️ 🕺