Skip to content

Screenshots

Jump to bottom
Kate Mueller edited this page Jul 11, 2024 · 7 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

The docs team uses Snagit for taking screenshots. This is a lightweight but full-featured screenshot tool. It allows us to use a shareable theme, to keep screenshots on-brand.

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

Snagit theme (internal users only)

  1. Download the theme: https://www.notion.so/n8n/Screenshots-and-diagrams-baf17e5d480b407aac643218a0043141?pvs=4#752f85845799458daa009ea9cf2e5c32
  2. Follow the Snagit docs to import it

Brand colors

We use the brand colors when annotating screenshots. These are included in the Snagit theme. If you don't have Snagit, add these colors to your screenshot tool:

  • #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

  • Use the Snagit theme
  • 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

Snagit has several techniques for removing or hiding parts of an image. Consider using the blur tool to hide irrelevant information and help users focus in on key parts of the image.

Note: don’t use the auto-simplify tool. This generates a fully simplified screenshot. In most cases, we want to offer our users more context than this allows.

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.

Modular files

All screenshots should include:

  1. The editable .snagx file
  2. The PNG to use in the docs

Save these together in the appropriate directory under docs/_images in the docs repo.

File size

Optimize your PNGs with https://tinypng.com/

Adding to docs

  • All screenshots must be accompanied by text that contains the same info
  • Always add alt text

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