Diagramming Tools

Markdown-based Diagramming Tools

• PlantUML
  • PlantUML
  • Inserting UML in Markdown using VSCode
• Mermaid
  • Mermaid Diagrams

Standalone Diagramming Tools

• Lucidchart
  • Lucidchart
• Draw.io (diagrams.net)
  • Draw.io
• Microsoft Visio
  • Microsoft Visio

Comparison Table

Feature/Tool	PlantUML	Mermaid	Lucidchart	Draw.io	Microsoft Visio
Type	Markdown-based	Markdown-based	Standalone	Standalone	Standalone
GitHub Support	Yes	Yes	No	No	No
DocFX Support	Yes	Yes	No	No	No
Ease of Use	Medium (requires syntax)	Medium (requires syntax)	High (GUI-based)	High (GUI-based)	High (GUI-based)
Collaboration	High (text-based)	High (text-based)	High (real-time)	High (real-time)	Medium (file-based)
Integration	High (code integration)	High (code integration)	Medium	Medium	Medium

Pros and Cons

Markdown-based Diagramming Tools

Pros:

• Text-based: Easy to version control and collaborate using text files.
• Integration: Can be integrated directly into documentation files (e.g., Markdown).
• Lightweight: No need for additional software; can be rendered by various tools and platforms.

Cons:

• Learning Curve: Requires learning specific syntax to create diagrams.
• Limited Features: May not have as many features as standalone tools.

Standalone Diagramming Tools

Pros:

• User-Friendly: Typically have a graphical user interface (GUI) that is easy to use.
• Feature-Rich: Often come with a wide range of features and templates.
• Real-Time Collaboration: Some tools offer real-time collaboration features.
• Customization: More customization options and a better user interface for creating diagrams.

Cons:

• Integration: Not as easily integrated into text-based documentation.
• Version Control: More challenging to version control compared to text-based diagrams.
• Cost: Some tools may require a subscription or purchase.
• Binary Files: Exported images are binary files that should not belong in Git.
• Editing: Users need to find the project file to edit and re-export the diagram.

Workflow Comparison

Markdown-based Diagramming Tools

1. Write the diagram in Markdown using the specific syntax (e.g., PlantUML, Mermaid).
2. Diagrams are generated automatically when the Markdown is rendered.

Standalone Diagramming Tools

1. Create the diagram using the standalone tool (e.g., Lucidchart, Draw.io, Microsoft Visio).
2. Export the diagram as an image.
3. Add the image to the documentation.
4. Note: The image is a binary file and should not belong in Git.
5. For edits, find the project file, make changes, and re-export the image.

Why Use One Over the Other?

• Markdown-based Tools: Ideal for developers who prefer to keep everything in text format, making it easier to version control and integrate with code. Suitable for projects where collaboration on text files is essential.
• Standalone Tools: Better for users who prefer a visual interface and need advanced features. Suitable for teams that require real-time collaboration and a wide range of diagramming capabilities. Also better for presentations.