Adding diagrams to documentation

Diagrams are useful in documentation to help illustrate engineering concepts and guides. However, it's important to ensure diagrams on fuchia.dev are accessible and updatable. This guide shows you how to add maintainable diagrams to Fuchsia documentation.

Types of diagrams

• Generate a simple flow diagram from text in the source code (example: Sequence Diagram or go/sequencediagram for Googlers)

• Create a visual diagram in Google Drawings, Slides, or other tool

How to add visual diagrams

If you are creating a visual diagram for documentation on fuchsia.dev, follow these steps:

1. Create a visual diagram in your tool of choice and export the image as a .svg (suggested) or .png file

• Optimize your image to ensure it loads quickly. Large images can slow down page load times.
• Use SVG (Scalable Vector Graphics) format whenever possible. SVGs are scalable, accessible, and have a smaller file size compared to other image formats.

1. Embed the image on fuchsia.dev using Markdown see instructions

• Store your image in the same directory as your Markdown file

1. Add alt text to the image. Alt text helps screen reader users understand the content of your image.

![Alt text](image_filename.svg)

• Replace Alt text with a concise description of the image
• Replace image_filename.svg with the actual filename of your image

Example:

![A flowchart showing the boot process of a Fuchsia device. The process starts
with the bootloader, then moves to Zircon kernel, and finally to the user
space.](component_framework.svg)

UX guidelines for diagrams

Diagrams are a useful tool for providing additional clarity or context that is not easily conveyed through words alone. Effective diagrams should directly support and enhance the accompanying text in documentation.

Focus: Each diagram should have a clear focus and convey a specific concept or idea. Label all elements clearly and concisely.

Simplicity: Strive for visual clarity. Avoid excessive complexity or visual clutter that might confuse the reader.

Consistency: Maintain a consistent style and visual language across all diagrams within Fuchsia documentation.

Internationalization: Keep text within diagrams to a minimum. If text is necessary, ensure it is translatable and localized. Use universally recognized symbols and icons whenever possible.

Design considerations

Visual hierarchy: Use clear and consistent visual hierarchy to guide the reader's eye through the diagram. Use whitespace to create visual separation and improve readability.

Color: Use sufficient color contrast to ensure readability for users with visual impairments. Avoid using color as the sole means of conveying information.

Scalability: Ensure diagrams are scalable and can be zoomed in without losing clarity.

Alt text

Provide concise and informative alternative text descriptions for all diagrams. Alt text should:

• Accurately describe the content and purpose of the diagram
• Use plain language that is easy for everyone to understand
• Be concise and to the point, avoiding unnecessary detail
• If a diagram contains text, include that text in the alt text

Alt text examples