Standards for images, custom visuals, and UI elements

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

Sourcing third-party images

Prefer natural colour 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:

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, and 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.

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

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

Embedding images

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

Additionally, image optimisation and responsive testing is the image committer’s responsibility.

Engineering-astro content images

Images referenced in the body content of .md, .mdx, and .astro files should be stored in the src/images directory and/or its subdirectories and referenced as shown below.

.astro and .mdx files

---
import { Image } from 'astro:assets';
---

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

.md and .mdx files

![required alt text]($images/path/to/image.png)

$images is an alias of the absolute path to src/images. However, it doesn’t work with image directives.

Engineering-astro jumbotron images

Jumbotron or banner images should be approximately 1200 x 600 pixels.

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.