For instructions to add images to markdown documents see adding images with markdown.
Screenshots and GIFs
Screenshots and GIFs can be incredibly useful when you’re demonstrating how to complete a task in a UI. When used well, they reassure users they’re on the right path and make following the steps frictionless. However, it's important not to over-rely on screenshots as UIs change, and you can confuse users when the screenshot doesn’t match the UI. It can also be hard for users to know exactly which part of the screenshot applies to them without additional guidance.
To help get the balance right, think of screenshots as signposts along the way. Don’t include screenshots for every step of a procedure, but to orient the user if:
- They might struggle to locate an item in the UI
- The procedure jumps from one place in the UI to another
- You want to reassure them they’re in the right place
For accessibility reasons, it’s also important not to rely solely on screenshots to convey information to users. When including screenshots, also describe the actions you expect the user to take.
Make sure any information conveyed in the screenshot supplements the text. If the UI changes and important steps are only documented with images, the user might struggle to follow the instructions.
Rules for screenshots (and GIFs)
- Use Google Chrome as your browser to take your screenshots.
- Use light not dark mode.
- Give the image file a descriptive name, i.e., variable-editor.png.
- Only use lowercase characters in the file name. DocSync validation fails if uppercase characters are present.
- Provide alt text for accessibility.
- Set the DPI for the image to 96, and keep the width under 1000px.
- Aim to keep the image file size below 200kb.
- Don't include the browser window "chrome" (the stuff around the page). Just include the page itself.
- Use green call-outs when you need to draw attention to some aspect of the UI. Use these colors:
- RGBA: 0, 204, 101, 255
- Hex: 00CC65
- Include enough of the window to orient users. Typically, in the Octopus web portal, include the navigation bar at the top of the page and the content of the screen you want to share.
- Reduce the whitespace. Don't take screenshots that are too wide, or include too much content at the bottom. Set your browser to somewhere between 1200px and 1400px wide. In Octopus, use the browser’s zoom function to remove as much whitespace as possible.
- Don't include version warning bars. Alpha and beta builds include the orange warning bar that you shouldn't show in screenshots.
- Sample data should look realistic. Take time to set up data that looks and feels somewhat realistic. Don't use your name.
- Don't stack screenshots. If want to include a screenshot that extends past the viewable window, use a tool like Snagit to capture a scrolling screenshot.
- Don't include the help window in the Octopus web portal. The help text is useful in the Octopus web portal, but it will make screenshots look crowded.
- Don't include the mouse cursor unless it's needed.
- Don't use screenshots to show commands the user needs. If the commands are in a screenshot, the user must manually copy them. Add them to a code block instead to make it easier for your reader.
- Include app windows. When you take a screenshot of an app, for example, Tentacle Manager, include the full window so users don't think they're seeing a webpage.
- Don't take screenshots over Remote Desktop. Remote Desktop tones down colors and disables clear type, so fonts aren't very clear.
The Octopus web portal - light versus dark theme
The Octopus UI has a light theme and a dark theme. We want our readers to have a consistent experience across our site when they see images of the UI. Unless you're specifically discussing the dark mode theme, use light mode for screenshots of the Octopus web portal. (This is also important because dark theme can trigger migraines in some people.)
Copyrighted images
We don't reuse a lot of images from external sources. If you have a genuine need to use an image from an external source, you need to check the copyright status of the image and whether you have permission to reuse the image.
Videos
To add a video to a blog post, add the video file to your blog post folder, then use the syntax below.
In this example, you've added your mp4 file to a blog post in the 2024-03 folder, in a folder called tak-log.
You can copy the syntax below but you'll need to update this part of the syntax: 2024-03/task-log/copy-paste.mp4 as relevant.
<video src="https://i.octopus.com/blog/2024-03/task-log/copy-paste.mp4" width="750" height="400" controls autoplay loop muted></video>