Images and Diagrams
This page describes how to format images and diagrams in documentation.
Images
When adding screenshots or other non-diagram images:
- Make sure that the original, editable file is in an accessible location with edit access.
- Make the file name a noun phrase.
- Save the file as a JPG (.jpg) file.
If you need the image to have some transparency, like making an image a specific shape, you can save the image as a PNG (.png) file. However, any text in the image must be within the shape of the image and in the transparent area. This is because, if text is laid over a transparent background, the text may be difficult to read if the page is in light or dark mode.
Diagrams
Depending on use case, you can create diagrams in one of two ways: as Mermaid diagrams or as JPG (.jpg) files.
Don't create diagrams in the ASCII format. ASCII diagrams lack a polished design, have formatting issues when double-byte Japanese characters are included, and require readers to scroll horizontally since the diagrams don't respond dynamically to different page widths.
Mermaid
For flowcharts and similar types of diagrams that don't contain a lot of text in space-constrained places, use Mermaid syntax when possible. Mermaid, which is supported by many popular static-site generators, make sure that diagrams have a single source of truth without having to manage a separate, editable file.
Some common types of Mermaid diagrams are:
JPG
For complex diagrams and diagrams that include a lot of text and/or are space constrained, diagrams in JPG (.jpg) format are acceptable
- Make sure that the original, editable file is in an accessible location with edit access.
- Make the file name a noun phrase.
- Save the file as a JPG (.jpg) file.
Don't save diagrams as PNG (.png) files. If a diagram is saved as a PNG (.png) file and has a transparent background, some parts of the diagram may be difficult to read if the page is in light or dark mode.