Skip to content

Media Standards

There are three primary types of media used in our documentation:

  • Screenshots: Visual representations of the user interface.
  • Instructional Images: Targeted visuals that illustrate specific steps or workflows.
  • Diagrams: Visualizations (such as ERD or UML diagrams) that explain engineering concepts or system architecture.

All media files should be stored in a folder named media or its subfolders within the documentation directory.

Screenshot Standards

Screenshots are essential for demonstrating product functionality. Follow these standards to ensure clarity and consistency:

  • Use Chrome's "Capture a full-page screenshot" for all screenshots.
  • Standardize screenshot widths:
    • 1920 px – Full Screen or List View
    • 1024 px – Center Panel (e.g., Edit or Job Form)
    • 760 px – Side Panels (Right or Left)
    • 360 px – Navbar
  • For consistent screenshots, create a custom device in Chrome with:
    • Width: 1280 px
    • Height: 960 px
    • Device Pixel Ratio: 1.5
    • User Agent: Desktop
  • Adjust height as needed to capture relevant content; avoid unnecessary context.
  • Always use Chrome's "Capture Screenshot" tool (not "Capture full size screenshot").
    • For specific widths, crop using an image editor (e.g., Preview on macOS or Paint.NET on Windows).
    • Keep partial screenshots clean—avoid cutting off sections awkwardly.
  • Save screenshots in PNG format.
  • Use realistic data in screenshots; avoid placeholder text like "foobar" or records generated by the generate_test_data factories.

  • Capture both light and dark modes, and include the source URL as a comment. Example:

    ![Filter Button](../../feature-guides/images/saved-views/filter-button_light.png#only-light){ .on-glb }
![Filter Button](../../feature-guides/images/saved-views/filter-button_dark.png#only-dark){ .on-glb }
[//]: # "`https://next.demo.nautobot.com/dcim/locations/`"

  • To highlight specific areas in a screenshot, use a red line with a thickness of 3 pixels.

  • After adding or modifying any screenshots, run poetry run invoke compress-images --fix --path ... to automatically optimize the images in the given directory for file size.

Instructions Standards

Generally, instructional images are created by Network to Code due to their complexity. As a result, the standards and guidelines for producing these images are maintained internally.

Diagram Standards

While we have not converged an single style, our standards for diagrams include:

  • Use Mermaid style for ERD or UML diagrams directly in markdown.
  • For other diagrams, maintain a single Draw.io file named nautobot-diagrams.drawio.
    • The first tab should map diagram topics to their corresponding files or documentation sections.
    • Each subsequent tab should focus on a specific diagram or topic.
    • Save the Draw.io file in XML format (not base64 or binary) so it can be tracked easier via version control in GitHub.