Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update diagram tooling to include Visio or PowerPoint #922

Merged
merged 3 commits into from Jan 23, 2023
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
29 changes: 22 additions & 7 deletions docs/design/design-reviews/recipes/preferred-diagram-tooling.md
@@ -1,15 +1,30 @@
# Preferred Diagram Tooling

At each stage in the engagement process, diagrams are a key part of the design review.
The preferred tooling for creating and maintaining diagrams is the `.drawio` format from [diagrams.net](http://diagrams.net) (formerly [draw.io](http://draw.io))
The preferred tooling for creating and maintaining diagrams is to choose **one** of the following:

The `.drawio` format uses the metadata layer within the PNG file-format to hide SVG vector graphics representation, then renders the .png when saving.
This clever use of both the meta layer and image layer allows anyone to further edit the PNG file.
It also renders like a normal PNG in browsers and other viewers, making it easy to transfer and embed.
Furthermore, it can be edited within VSCode very easily using the [Draw.io Integration VSCode Extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio).
- Microsoft Visio
benjguin marked this conversation as resolved.
Show resolved Hide resolved
- Microsoft PowerPoint
- The `.drawio.png` (or `.drawio`) format from [diagrams.net](http://diagrams.net) (formerly [draw.io](http://draw.io))

In all cases, we recommend storing the exported PNG images from these diagrams in the repo along with the source files so they can easily be referenced in documentation and more easily reviewed during PRs. The `.drawio.png` format stores both at once.

## Microsoft Visio

It contains a lot of shapes out of the box, including Azure icons, the desktop app exists on PC, and there's a great Web app. Most diagrams in the Azure Architecture Center are Visio diagrams.

## Microsoft PowerPoint

Diagrams can be easily reused in presentations, a PowerPoint license is pretty common, the desktop app exists on PC and on the Mac, and there's a great Web app.

## `.drawio.png`

There are different desktop, web apps and VS Code extensions.
This tooling can be used like Visio or LucidChart, without the licensing/remote storage concerns.
Furthermore, Diagrams.net has a collection of Azure/Office/Microsoft icons, as well as other well-known tech, so it is not only useful for swimlanes and flow diagrams, but also for architecture diagrams.

Furthermore, we recommend storing the exported PNG images from these diagrams in the repo along with the .drawio files so they can easily be referenced in documentation and more easily reviewed during PRs.
Lastly, while diagrams.net is generally preferred, if any other diagraming tooling is used that can generate diagram images from code, both the diagram file and the image file should be stored together in the repo for the above reasons.
`.drawio.png` should be preferred over the `.drawio` format.
The `.drawio.png` format uses the metadata layer within the PNG file-format to hide SVG vector graphics representation, then renders the .png when saving.
This clever use of both the meta layer and image layer allows anyone to further edit the PNG file.
It also renders like a normal PNG in browsers and other viewers, making it easy to transfer and embed.
Furthermore, it can be edited within VSCode very easily using the [Draw.io Integration VSCode Extension](https://marketplace.visualstudio.com/items?itemName=hediet.vscode-drawio).