Screenshots

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 handline 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

1. Download the theme:

   n8n-docs-2022.snagtheme

2. Follow the Snagit docs to import it

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