Standards for images, custom visuals, and UI elements in [#technical-documentation]

LinkORB has the following requirements for using images, custom visuals, and UI elements in technical documents:

Sourcing third-party images

Prefer natural color images that evoke LinkORB’s human, modest, but technically-inspired vibes when using third party images.

Do not use copyrighted images from sites like https://images.google.com or Shutterstock. Instead, use photos, illustrations, and icons from third-party sources that offer royalty-free licences such as the following:

• StockSnap: Millions of CCO license images with no usage restrictions.
• unDraw: Open-source customizable .svg and .png illustrations. Attribution is optional.
• Pixabay: Free use vector images, illustrations, and photos accessible from a browser or an API. Attribution is optional.
• Pexels: Royalty free photos. Attribution is optional.
• Feather icons: Open-source, customizable icons.
• Bootstrap Icons: Available as standalone vector images, a zip archive, or an npm package.
• Unsplash: Free use and paid photos, vector images, illustrations accessible through the browser or an API. Attribution is optional.

Please see Free Open Source Icon Libraries or Free Open-Source Icons for a list of open-source resources that offer free icons and illustrations.

Attribution for images in articles

Wrap the image’s URL and the photographer’s/illustrator’s name in <p> tags directly below the image and set img-attribution as the p tag’s class as shown below.

<p class="img-attribution">
    Source: <a href="https://img.example.com">Photographer's or Illustrator's name</a>
</p>

Attribution for jumbotron images

Add the imgAttributionName and imgAttributionUrl to a Markdown document’s frontmatter as shown below.

imgAttributionName: Photographer's or Illustrator's name
imgAttributionUrl: https://link.to.image/source

Embedding custom visuals

While a picture can be worth a thousand words, a custom visual can be worth ten thousand. When helpful, writers should include diagrams, flowcharts, work breakdown structures, other custom imagery that support the reader’s understanding of a topic.

As part of LinkORB’s “documentation is code”, custom visuals should leverage one of the below Markdown solutions.

• Mermaid.js
• PlantUML
• C4Model

Read more at Use Mermaid.js and PlantUML to build custom visuals.

While use of colors in custom visuals can enhance their effectiveness and promote information hierarchy, colors should also be used judiciously as to not overwhelm the reader. Please see Brand and styling consistency for specific color guidance.

Embedding images

Embedded images (.svg, .jpeg, .png, .webp) should be stored in the same repository as the document it supports.

Additionally, image optimization and responsive testing is the image commiter’s responsibility.

Engineering-astro content images

When working on engineering-astro, .webp is the preferred image format.

Images referenced in body content of .md files should be stored in the /public/img/ directory or subdirectories.

To facilitate conversion of .jpeg and .png images, the repository contains a convert-images.js script. This script can be executed manually in a terminal with the below.

npm run convert-images

It is suggested to convert images to .webp before referencing the image file in Markdown.

As per Astro conventions, images referenced in body content of .mdx or .astro files should be stored in the /src/images directory or subdirectories.

To facilitate conversion of images in .mdx and .astro files, @astrojs/image provides the format property for on-the-fly conversion. An example is provided below.

<Image src="/src/images/landscape.webp" alt="A landscape image" format="webp"/>

Engineering-astro jumbotron images

Jumbotron or banner images should be approximately 1200 x 600 pixels. Their conversion to .webp is managed automatically in the Jumbotron.astro component.

Repository-specific image location

Save images specific to a repository’s documentation in the repository’s docs/img folder. Repository-specific images include all images used in a repository’s README.md file and documentation saved in the repository’s docs folder.

Screenshots

While screenshots can provide additional context, they also introduce issues relating to page rendering, information layout, and are more difficult to modify than text. Avoid using screenshots of commercial applications. Only use a screenshot if it adds distinct, material value to a document.

Limit the use of screenshots when documenting:

• applications
• user interface elements
• code
• command line output
• configuration files

When documentation is targeted at a technical audience, screenshots are less necessary. Instead:

• Write a numbered list of steps. It’s shorter and easier to read.
• Emphasize user interface elements (e.g. Click Save). Use imperative tone.
• Share important command line output, error messages, sample code, and similar information within a code fence. This makes content more searchable and more easily editable.

As discussed in Standards for written content, use an open-source approach. Screenshots should not include specific internal projects, team member names, or LinkORB-only concepts.