What Size Should Documentation Screenshots Be?

One capture width, one display width, and a decision about retina. The three numbers that determine whether your images look sharp or soft.

Last updated August 2026

You will finish with three numbers written down: the width you capture at, the width the image displays at in an article, and whether you are capturing at 1x or 2x. Those three decide whether your screenshots look sharp, and almost nothing else does.

Before you start

Find out how wide your help centre actually renders images. Open an article, right-click an image, inspect it, and read the rendered width. Most help centres constrain article content to somewhere between 650px and 800px, and every decision below follows from that number.

The same interface text rendered at one times and two times density, both displayed at the same size. The one times version is visibly softer.

Both shown at the same display size. The difference is capture density, not the export.

Steps

Capture at 1440px browser width as a default.
Wide enough that layouts look like the real product, narrow enough that interface text survives being scaled down to article width. Wider captures put more pixels into things nobody needs to read.
Capture at 2x device pixel ratio.
A 2x capture of a 1440px viewport produces a 2880px-wide file. Displayed at 700px, it has roughly four times the pixel density it strictly needs, and it will look sharp on every display anyone owns. This matters more than any other choice here.
Export at no more than twice your display width.
If articles render images at 700px, export at 1400px. Anything beyond that is bytes with no visible benefit - the extra resolution cannot be seen at the size the image is shown.
Crop before you scale.
A screenshot of one panel, cropped to that panel and displayed at 700px, is far more legible than a full window scaled to the same width. Crop to the subject and the effective resolution rises for free.
Set explicit width and height attributes.
Whatever renders your articles, make sure the image dimensions are declared. Without them the page reflows as images load, which is both unpleasant and a measurable Core Web Vitals penalty.
Check legibility at actual size.
View the published article at 100% zoom on a normal laptop. If the interface text in the image is smaller than the article's body text, the image is too wide or the crop is too loose.
Use the same numbers every time.
The specific values matter less than their consistency. Mixed capture widths produce images whose interface elements are different physical sizes across articles, which reads as sloppiness.

Common mistakes

Capturing at 1x and hoping. A 1x capture displayed on a retina screen is being upscaled, and it looks soft in exactly the way readers describe as "low quality" without knowing why.

Exporting at full retina resolution. The opposite error. A 2880px image displayed at 700px is roughly four times the bytes it needs, and screenshot-heavy articles get slow.

Capturing a maximised window on a large monitor. A 2560px-wide capture shows a layout most users never see and scales down to illegibility.

Zooming the browser out to fit more in. This makes interface text smaller relative to everything else, so the image looks blurry at any export size. Crop instead.

Different sizes for the same UI element across articles. The same button appearing at three different physical sizes is one of the more noticeable inconsistencies available, and it comes entirely from varying capture width.

When this stops scaling

Getting these three numbers right is a one-time decision, and that is genuinely the good news here - unlike most screenshot problems, this one does not recur.

What does recur is applying them. Every capture is another opportunity to have the browser at the wrong width, or to export at whatever the tool defaulted to. Nothing in the workflow enforces the numbers; they live in a document and rely on whoever is capturing remembering to check.

The failure is quiet, too. A slightly-wrong export size does not look broken on its own - it only shows up as a set that does not quite cohere, six months and forty images later, at which point tracing it back to capture settings is archaeology.

Where images are rendered rather than captured, the dimensions are a parameter rather than a habit: every image comes out at the same size because the same code produced it. SupportPages generates documentation images from your repository's own stylesheet at a fixed size. If you have ever found three different capture widths in one help centre, that is the difference between a convention and a constraint.