Screenshots are a balance between the value of accurate ones, the impact of inaccurate ones, and the burden of maintenance. We aim to generously provide visual references for our readers that include just as much detail as they need while avoiding frequently changing elements that will increase the maintenance burden.
Not everyone reading the docs has opened an account. Product docs can play a key element as decision makers screen products for further evaluation, and our control panel is our differentiator. In addition, screenshots can make it easier for users to spot what they need on the page, even when the words describe what to do.
Screenshots also bolster confidence for readers. Seeing forms with values filled in can be easier for readers to compare to their own screens than lining up words in directions with field labels on the screen.
Screenshots should be PNG format. (Some graphics will be better served by jpgs. Screenshots aren’t one of those.)
Browser viewport: 1375px by at least 955px.
Avoid dual scrollbars, which requires a minimum height of 955px. The image may be taller or cropped depending on what’s being shown, but adjust the browser height so that the scrollbars aren’t visible and the width remains consistent.
Content area screenshots: 1150px x 1115px
Most screenshots will not include the side nav or header nav. Do not upload images of a single button or piece of the content area without the width of the rest of the pages.
Optimize your images. Screenshots are often quite large in terms of file size on disk, but also very easily compressed. Once you have a screenshot that you are satisfied with, use TinyPNG or some other sort of utility that allows you to compress the images. Screenshot compression often results in a 50-75% reduction in file size, so it’s well worth it!
Show how to find elements in the UI reliably (e.g. don’t rely on Dashboard cues). Show the top nav with the Create menu expanded when that works; describe nav and show the create page when it doesn’t (e.g. PTR records).
Show only content. When describing how to fill out something that’s not obvious or where the page is busy, show the context (e.g. the DNS record entry), Always describe it in words as well. We should be able to say “Screenshot of the [specific] UI described above/below”.
Exclude browser chrome whenever possible, especially scroll bars. However, sometimes it’s advantageous to show the location bar, usually in a procedural tutorial. In this case:
Exclude the left nav and header in all screenshots that aren’t specifically discussing an item in the nav and consider when a screenshot is really needed in those cases.
Avoid stray cursors, but do include the cursor to draw attention where you want it.
Include descriptive alt text.
We need to be careful we’re not leaking upcoming product and feature releases. Our screenshots should provide a company presence, not a personal account visual, so:
Always use a test account and be aware of what’s been feature-flipped there.
Use a default DigitalOcean avatar, not one you upload yourself.
Display IP addresses in the documentation ranges (as in RFC-5737). Edit the DOM via a browser’s inspector for this.
Once you have a screenshot that you want to use, you need to do a couple of things.
Place it in an appropriate subfolder under assets/images. All new screenshots should go into this folder, but except under rare circumstances, should always be placed into an appropriate subfolder. We don’t want the root to get too cluttered. If you’re not sure where to place an image, feel free to ask!
Use the image shortcode. It will generate your image tag appropriately, while also working with Hugo’s pipelines to properly fingerprint the asset for caching purposes. Check out the image shortcode documentation for more information and examples.