Skip to content

Screenshots

Jump to bottom
Nick Veitch edited this page Feb 3, 2025 · 8 revisions

Introduction

The aim is to create screenshots that:

  • Are clear, and help the user get the info they need
  • Have as little maintenance overhead as possible
  • Are accessible

Understand: this Write the Docs talk is well worth a watch. It sets out the challenges of screenshots, and some techniques for handling them. The speaker works on a large team, so not everything applies to us (given the difference in scale), but it’s useful background.

Do you need a screenshot?

Every image adds maintenance load and data consumption.

  • Don’t add screenshots just to be decorative or break up text (if you find you have a wall of text, you may need more subheadings or lists)
  • Is the process clear enough with just text? If so, do you really need a screenshot?

Add a screenshot if it’s very hard to be clear about the information in text, or if users are regularly confused by this part of the UI.

Tooling

Brand colors

We use the brand colors when annotating screenshots.

  • #101330 - a dark blue. Use this for most annotations (arrows, boxes, text)
  • #1C9985 - green. Use as secondary color if needed, or if blue won't stand out.
  • #BF2F51 - pink/red. Rarely used. Bit of a danger signal

Creating a screenshot

  • Avoid gifs. Because:
    • We have a growing amount of marketing video to cover this gap
    • gifs are a pain for both data load and maintenance
    • Do step by step screenshots instead
  • Only the Editor UI appears in the screenshot. Anything else, like the browser frame, tabs, and so on, should be omitted.
  • When screenshotting workflows:
    • Ensure the nodes have a distance of two boxes between them.
    • Centre the workflow on the canvas
    • If the workflow uses a trigger node, make the sure the start node isn’t visible
  • Keep the visuals clean: every box/arrow/annotation should have a purpose. Avoid visual noise.
  • Annotations should be brief. They should be supplemental to the text of the document.
  • When adding a box, use a rectangle with rounded corners.

Hiding parts of the image

Consider using the blur tool to hide irrelevant information and help users focus in on key parts of the image.

Warning: simply blurring out information is not a secure way of hiding it. If your screenshot includes sensitive information, replace that information with fake examples before taking the screenshot.

Saving an image

Image directories

The images live with the docs source code in the git repo. There is a dedicated _images directory.

  • Do not put images in with content files. They should all live under _images
  • Generally, recreate the docs structure within the _images directory, with a directory for each document. For example, https://docs.n8n.io/editor-ui/ has images located in _images/editor-ui Note that there are exceptions to this rule.
  • Exception1: for commonly-used icons, place these in _images/common-icons
  • Exception 2: The current structure reflects resources inherited from a previous docs setup. You may sometimes find screenshots grouped by section rather than doc. This is gradually being overhauled.

File size

Optimize your PNGs (this is usually an option when saving from most tools).

Adding to docs

Use this format:

<figure markdown="span">
![Enter alt text here](/my/relative/image/path/filename.png)
<figcaption>Enter image caption here</figcaption>
</figure>
Clone this wiki locally