Technical Writing and Documentation 101: Graphics and Diagram Tools (Draw.io, Lucidchart, Snagit)

Graphics and Diagram Tools (Draw.io, Lucidchart, Snagit)

Graphics and Diagram Tools for Technical Writers

A Practical Study Guide for Aspiring & Modernizing Writers

What This Is

Graphics and diagrams turn complex technical concepts into clear, visual explanations. They’re essential for API documentation (e.g., sequence diagrams for OAuth flows), cloud architecture guides (e.g., AWS service interactions), and software tutorials (e.g., UI workflows in a SaaS app). For example, a payment gateway API reference might use a flowchart to show how a transaction moves from checkout to bank approval, or a screenshot with annotations to highlight key fields in a dashboard. Without visuals, users waste time deciphering walls of text—leading to frustration and support tickets.

Key Terms & Tools

• Vector vs. Raster Graphics
• Vector: Scalable images (e.g., .svg, .drawio) made of paths (ideal for diagrams, logos). Never pixelates.

• Raster: Pixel-based images (e.g., .png, .jpg) that lose quality when resized (good for screenshots).

• Draw.io (now Diagrams.net)

• Free, browser-based diagramming tool with templates for UML, flowcharts, network diagrams, and AWS/GCP architectures. Exports to .svg, .png, or .pdf. Integrates with Confluence, Google Drive, and GitHub.

• Lucidchart

• Paid diagramming tool with real-time collaboration (like Google Docs for diagrams). Supports data linking (e.g., auto-updating diagrams from a spreadsheet) and Visio import/export. Used for enterprise architecture docs.

• Snagit

• Screenshot and screen recording tool with annotations (arrows, callouts, blurs) and GIF creation. Ideal for step-by-step tutorials (e.g., "How to configure a webhook in Slack").

• Mermaid.js

• Text-based diagramming (write code to generate diagrams). Used in Markdown files (e.g., GitHub READMEs) or docs-as-code workflows. Example:
  mermaid
graph TD;
A[User Clicks 'Pay'] --> B{Valid Card?};
B -->|Yes| C[Process Payment];
B -->|No| D[Show Error];

• UML (Unified Modeling Language)

• Standardized diagrams for software design:

  
  
  • Class diagrams (show relationships between objects, e.g., User → Order).
  • Sequence diagrams (show interactions over time, e.g., API request/response flows).

• SVG (Scalable Vector Graphics)

• XML-based vector format. Editable in code (e.g., tweak colors in a text editor) and accessible (screen readers can describe shapes). Use for logos, icons, and diagrams in web docs.

• Alt Text

• Descriptive text for images (e.g., "Flowchart showing OAuth 2.0 authorization code flow with steps: 1. User requests login, 2. Redirect to auth server..."). Critical for accessibility and SEO.

• Docs-as-Code Diagrams

• Storing diagrams as code (Mermaid, PlantUML) or version-controlled files (.drawio, .svg) in Git. Enables automated updates (e.g., CI/CD pipelines that rebuild docs when diagrams change).

• Wireframes vs. Mockups

• Wireframe: Low-fidelity sketch of a UI (e.g., boxes for buttons, placeholder text). Used early in design.

• Mockup: High-fidelity, detailed UI (e.g., actual colors, fonts, images). Used for final reviews.

• Confluence Diagrams

• Atlassian’s built-in drawing tool (limited) or Gliffy/Draw.io plugins for embedding diagrams in wiki pages. Use macros to link diagrams to Jira tickets.

Step-by-Step: Creating a Diagram for Technical Docs

1. Define the Purpose & Audience

• Action: Ask:
• What problem does this diagram solve? (e.g., "Users don’t understand how data flows between microservices.")
• Who’s the audience? (Developers? Non-technical stakeholders? Support teams?)
• Example: For a cloud migration guide, you might need:
• A network diagram for engineers.
• A simplified flowchart for executives.

2. Choose the Right Tool & Format

• Action:
• For code-based docs (Markdown, GitHub): Use Mermaid.js or PlantUML.
• For interactive docs (Confluence, Notion): Use Draw.io or Lucidchart.
• For tutorials with screenshots: Use Snagit (for annotations) + .png (for clarity).
• Pro Tip: Export diagrams as .svg (scalable) and .png (fallback for email/PDFs).

3. Draft the Diagram

• Action:
• Start with a template (e.g., Draw.io’s "AWS Architecture" or "UML Class Diagram").
• Use consistent styling:
  • Colors: Stick to brand palette or accessible contrasts (e.g., avoid red/green for colorblind users).
  • Fonts: Use one font family (e.g., Arial for labels, bold for emphasis).
  • Shapes: Use standard symbols (e.g., cylinders for databases, clouds for SaaS).
• Label clearly:
  • Use short, active phrases (e.g., "User submits form" vs. "Form submission by user").
  • Add callouts for key details (e.g., "Note: This step requires admin permissions").
• Example: Draw.io AWS Architecture Template

4. Test for Clarity & Accuracy

• Action:
• Peer review: Ask a colleague, "What does this diagram show?" If they hesitate, simplify.
• Accessibility check:
  • Run the .svg through WAVE to test color contrast.
  • Add alt text (e.g., "Sequence diagram: User login flow with steps 1-5").
• Technical validation: For API diagrams, verify with engineers that the flow matches the actual code.

5. Export & Embed in Docs

• Action:
• For web docs (Markdown, HTML):
  • Embed Mermaid code directly (renders on GitHub/GitLab).
  • Upload .svg to your docs repo and link it (e.g., ![Diagram](path/to/diagram.svg)).
• For PDFs/Word:
  • Export as .png (300 DPI for print quality).
  • Use Snagit’s "Smart Move" to highlight interactive elements.
• For Confluence:
  • Use the Draw.io plugin to embed editable diagrams.
  • Set versioning (e.g., "Diagram v2 – Updated 2024-05-01").

6. Automate Updates (Docs-as-Code)

• Action:
• Store diagrams in Git (e.g., /docs/diagrams/).
• Use CI/CD (e.g., GitHub Actions) to:
  • Auto-generate Mermaid diagrams from Markdown.
  • Convert .drawio to .svg on PR merges.
• Example Workflow:
  yaml
# .github/workflows/generate-diagrams.yml
name: Generate Diagrams
on: [push]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
- run: npx @mermaid-js/mermaid-cli -i docs/flowchart.md -o docs/flowchart.svg

Common Mistakes

Tech Writing Interview / Portfolio Tips

What Hiring Managers Look For

1. Tool Proficiency
2. Be ready to discuss Draw.io vs. Lucidchart (e.g., "I use Draw.io for open-source docs because it’s free and integrates with GitHub, but Lucidchart for team collaboration").

3. Know Mermaid.js for docs-as-code roles (e.g., "I embedded Mermaid diagrams in Markdown to auto-generate API sequence flows").

4. Diagram Types for Different Docs

5. API Docs: Sequence diagrams, data flow diagrams.
6. Tutorials: Screenshots with annotations, GIFs for workflows.
7. Architecture Guides: UML class diagrams, cloud architecture diagrams (AWS/GCP templates).

8. Troubleshooting: Decision trees (e.g., "If error X, check Y; if error Z, do A").

9. Portfolio Examples

10. Include before/after examples (e.g., "I replaced a 500-word explanation with this flowchart, reducing support tickets by 30%").
11. Show collaboration (e.g., "I worked with engineers to validate this sequence diagram for our OAuth flow").

12. Highlight automation (e.g., "I set up a GitHub Action to auto-generate Mermaid diagrams from Markdown").

13. Tricky Distinctions

14. Wireframe vs. Mockup: Wireframes are low-fidelity (sketches), mockups are high-fidelity (detailed).
15. Flowchart vs. Sequence Diagram: Flowcharts show steps in a process, sequence diagrams show interactions over time (e.g., API calls).
16. Raster vs. Vector: Raster (.png) is for screenshots, vector (.svg) is for diagrams/logos.

Quick Check Questions

1. A developer says, "The diagram in the API docs doesn’t match the actual code flow." How do you fix this?

Answer: Validate the diagram with the engineering team, update it to match the current code, and add a version label (e.g., "v1.2 – Updated 2024-05-01"). For docs-as-code, automate diagram generation from the codebase (e.g., using Mermaid or PlantUML).
Why: Diagrams must stay in sync with code to avoid misleading users.

2. Your manager asks for a diagram showing how a user’s data moves through your app’s microservices. What type of diagram do you create?

Answer: A data flow diagram (showing services as nodes and data as arrows) or a sequence diagram (showing interactions over time). Use Draw.io’s AWS/GCP templates for cloud services or Mermaid.js for code-based docs.
Why: These diagrams clearly visualize where data goes and how it’s processed.

3. A tutorial you wrote has a screenshot of a UI, but the UI changed in the latest release. How do you update the docs efficiently?

Answer: Replace the screenshot with a vector-based wireframe (e.g., Draw.io) or use Snagit’s "Smart Move" to update only the changed elements. For future-proofing, avoid screenshots for dynamic UIs—use annotated wireframes instead.
Why: Vector/wireframe updates are faster and less prone to breaking than raster screenshots.

Last-Minute Cram Sheet

1. Draw.io: Free, browser-based, integrates with GitHub/Confluence. Export as .svg for scalability.
2. Lucidchart: Paid, real-time collaboration, Visio-compatible. Use for enterprise docs.
3. Snagit: Best for screenshots + annotations (e.g., tutorials). Use GIFs for short workflows.
4. Mermaid.js: Write diagrams in code (e.g., GitHub Markdown). Example:
   mermaid
graph LR; A-->B; B-->C;
5. SVG > PNG: Always use .svg for diagrams (scalable, editable, accessible).
6. Alt Text: Describe the purpose (e.g., "Flowchart: OAuth 2.0 authorization code flow"), not just the content.
7. Docs-as-Code: Store diagrams in Git and automate updates with CI/CD.
8. UML Basics:
9. Class diagram: Objects + relationships (e.g., User → Order).
10. Sequence diagram: Interactions over time (e.g., API calls).
11. Accessibility: Test color contrast with WAVE. Avoid red/green for statuses.
12. ⚠️ Trap: A tutorial diagram should guide the user step-by-step (e.g., numbered callouts), not just show the end state.