Just sharing some experience from writing technical articles recently.
When writing documents in Markdown or LaTeX, I often need to insert diagrams or charts. After trying different tools and approaches, I’ve found a workflow that works really well for software engineers.
My setup
- Start the Markdown or LaTeX project in VS Code (or any IDE)
- Ask AI to:
- Use D2 to generate diagrams
- Use Python to generate charts
- Run the commands itself and output the images
Why this works well
- D2 is excellent for diagrams (architecture, flowcharts, system design)
- You can ask AI to apply specific styles or themes
- The syntax is simple and readable
- Easy to maintain and modify later
- D2 is not great for charts
- That’s where Python (matplotlib, etc.) shines
- Each tool focuses on what it does best:
- D2 → diagrams
- Python → charts
Installing D2 on macOS (Homebrew)
If you’re on macOS, installing D2 is straightforward with Homebrew:
brew install d2
Verify the installation:
d2 --version
Extra tips
- Ask AI to keep the D2 or Python code it generated(useful for future edits and version control)
- Ask AI to insert the generated images directly into your Markdown or LaTeX files
- This keeps everything reproducible and easy to maintain
Overall, this combination has been the most efficient and engineer-friendly workflow I’ve found so far.
Hope this helps someone writing technical docs 