167 lines
4.9 KiB
Markdown
167 lines
4.9 KiB
Markdown
|
# Format Selection Guide
|
||
|
|
|
||
|
|
Choose the right diagram format based on your needs.
|
||
|
|
|
||
|
|
## Quick Decision Matrix
|
||
|
|
|
||
|
|
| Factor | Draw.io | Mermaid | Excalidraw |
|
||
|
|
|--------|---------|---------|------------|
|
||
|
|
| **Learning curve** | Low | Low | Low |
|
||
|
|
| **Quick generation** | Medium | **High** | Medium |
|
||
|
|
| **Manual editing** | **Excellent** (GUI) | Code-based | Good (GUI) |
|
||
|
|
| **Version control** | XML (verbose) | **Markdown** (clean) | JSON |
|
||
|
|
| **Code documentation** | Medium | **Excellent** | Poor |
|
||
|
|
| **Complex nesting** | **Excellent** | Poor | Good |
|
||
|
|
| **Custom styling** | **Excellent** | Limited | Good |
|
||
|
|
| **Hand-drawn style** | No | No | **Yes** |
|
||
|
|
| **Export options** | PDF, PNG, SVG, etc. | PNG, SVG | PNG, SVG, JSON |
|
||
|
|
|
||
|
|
## When to Use Draw.io
|
||
|
|
|
||
|
|
### Ideal For:
|
||
|
|
- **Network topology diagrams** with nested environments/datacenters/zones
|
||
|
|
- **Complex architecture diagrams** with many layers
|
||
|
|
- **Diagrams requiring fine-grained control** over positioning and styling
|
||
|
|
- **Professional technical diagrams** for documentation
|
||
|
|
- **Diagrams that need manual refinement** after generation
|
||
|
|
|
||
|
|
### Examples:
|
||
|
|
- Enterprise network topology (environments → datacenters → zones → devices)
|
||
|
|
- Microservices architecture with many components
|
||
|
|
- System diagrams with custom icons and layouts
|
||
|
|
- Production infrastructure maps
|
||
|
|
|
||
|
|
### Strengths:
|
||
|
|
- Best-in-class nested container support (swimlanes)
|
||
|
|
- Powerful GUI editor for fine-tuning
|
||
|
|
- Export to multiple formats (PDF, PNG, SVG)
|
||
|
|
- Large library of pre-built shapes and icons
|
||
|
|
- Supports multiple pages in one file
|
||
|
|
|
||
|
|
### Weaknesses:
|
||
|
|
- XML format is verbose (larger files)
|
||
|
|
- Not ideal for quick iterations
|
||
|
|
- Manual positioning can be time-consuming
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## When to Use Mermaid
|
||
|
|
|
||
|
|
### Ideal For:
|
||
|
|
- **Documentation embedded in code** (Markdown files)
|
||
|
|
- **Quick flowcharts and sequence diagrams**
|
||
|
|
- **Version-controlled diagrams** (clean git diffs)
|
||
|
|
- **Technical documentation** (README, API docs)
|
||
|
|
- **Simple to moderately complex diagrams**
|
||
|
|
|
||
|
|
### Examples:
|
||
|
|
- User authentication flow
|
||
|
|
- API sequence diagram
|
||
|
|
- Class diagram for a module
|
||
|
|
- ER diagram for a database
|
||
|
|
- Git workflow visualization
|
||
|
|
|
||
|
|
### Strengths:
|
||
|
|
- Text-based, easy to version control
|
||
|
|
- Can be embedded in Markdown
|
||
|
|
- Renders in GitHub, GitLab, many markdown editors
|
||
|
|
- Compact syntax
|
||
|
|
- Good support for UML diagrams (class, sequence, state, activity)
|
||
|
|
|
||
|
|
### Weaknesses:
|
||
|
|
- Limited styling options
|
||
|
|
- Poor support for complex nesting
|
||
|
|
- Layout is auto-generated (less control)
|
||
|
|
- No GUI editor (must edit code)
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## When to Use Excalidraw
|
||
|
|
|
||
|
|
### Ideal For:
|
||
|
|
- **Hand-drawn / informal diagrams**
|
||
|
|
- **Brainstorming sessions** and mindmaps
|
||
|
|
- **Creative diagrams** with custom freeform elements
|
||
|
|
- **Informal presentations** that feel more human
|
||
|
|
|
||
|
|
### Examples:
|
||
|
|
- Whiteboard-style architecture sketches
|
||
|
|
- Meeting notes with diagrams
|
||
|
|
- Brainstorming mindmaps
|
||
|
|
- Informal process flows
|
||
|
|
- Wireframes (basic)
|
||
|
|
|
||
|
|
### Strengths:
|
||
|
|
- Unique hand-drawn aesthetic
|
||
|
|
- Freeform drawing capability
|
||
|
|
- Excellent for creative/brainstorming scenarios
|
||
|
|
- Can embed in web pages (ExcalidrawEmbed)
|
||
|
|
- Good sharing and collaboration features
|
||
|
|
|
||
|
|
### Weaknesses:
|
||
|
|
- Not ideal for precise technical diagrams
|
||
|
|
- JSON format is verbose and hard to edit manually
|
||
|
|
- Limited support for complex relationships
|
||
|
|
- Less standard in technical documentation
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## Decision Tree
|
||
|
|
|
||
|
|
```
|
||
|
|
Start
|
||
|
|
│
|
||
|
|
├─ Need hand-drawn style?
|
||
|
|
│ └─ Yes → Excalidraw
|
||
|
|
│ └─ No → Continue
|
||
|
|
│
|
||
|
|
├─ Complex nesting (4+ levels)?
|
||
|
|
│ └─ Yes → Draw.io
|
||
|
|
│ └─ No → Continue
|
||
|
|
│
|
||
|
|
├─ Need fine-grained positioning/styling?
|
||
|
|
│ └─ Yes → Draw.io
|
||
|
|
│ └─ No → Continue
|
||
|
|
│
|
||
|
|
├─ Embedding in documentation/GitHub?
|
||
|
|
│ └─ Yes → Mermaid
|
||
|
|
│ └─ No → Continue
|
||
|
|
│
|
||
|
|
├─ Quick iteration needed?
|
||
|
|
│ └─ Yes → Mermaid
|
||
|
|
│ └─ No → Draw.io
|
||
|
|
```
|
||
|
|
|
||
|
|
## Format Comparison by Diagram Type
|
||
|
|
|
||
|
|
| Diagram Type | Recommended | Alternative |
|
||
|
|
|--------------|--------------|-------------|
|
||
|
|
| Simple Flowchart | **Mermaid** | Draw.io (if styling needed) |
|
||
|
|
| Complex Flowchart (10+ nodes) | **Draw.io** | Mermaid (if auto-layout works) |
|
||
|
|
| Sequence Diagram | **Mermaid** | Draw.io |
|
||
|
|
| Class Diagram | **Mermaid** | Draw.io |
|
||
|
|
| ER Diagram | **Mermaid** | Draw.io |
|
||
|
|
| Mindmap | **Mermaid** | Excalidraw (for hand-drawn) |
|
||
|
|
| Network Topology | **Draw.io** (required) | - |
|
||
|
|
| System Architecture | **Draw.io** | Mermaid (for high-level) |
|
||
|
|
| Whiteboard Sketch | **Excalidraw** | Draw.io (formal) |
|
||
|
|
| Brainstorming | **Excalidraw** | Mermaid (structured) |
|
||
|
|
|
||
|
|
## Migration Considerations
|
||
|
|
|
||
|
|
### Draw.io → Mermaid
|
||
|
|
- Remove nested containers (Mermaid doesn't support)
|
||
|
|
- Simplify styling
|
||
|
|
- Convert XML to Mermaid syntax
|
||
|
|
- Use auto-layout (may need manual adjustment)
|
||
|
|
|
||
|
|
### Mermaid → Draw.io
|
||
|
|
- Import or recreate manually
|
||
|
|
- Gain manual control over layout
|
||
|
|
- Add nested containers if needed
|
||
|
|
|
||
|
|
### Any Format → Excalidraw
|
||
|
|
- Recreate manually in Excalidraw editor
|
||
|
|
- Hand-drawn aesthetic adds informal feel
|
||
|
|
- Good for brainstorming iterations
|