Skip to content

Style Guide

Jump to bottom
Nick Trogh edited this page Jan 15, 2026 · 9 revisions

Introduction

One of the goals of our documentation is to get users to "wow" faster. This includes helping them learn what they need to learn to have an excellent experience in VS Code in the shortest amount of time possible and with the least amount of effort on their part.

Well-taken screenshots can break up the monotony of reading and help users more easily understand what they need to know.

Images and screenshots

When to use screenshots

  • The UI is visual or spatial (layouts, menus with icons)
  • The user must identify something by appearance
  • The step can't be clearly described with text alone

Screenshot content rules

Include only what matters

  • Leave out OS chrome, unless it is relevant to the subject matter
  • Crop screenshots to show only the particular feature we are demonstrating
  • Avoid chopping of content - as much as possible, we should not partially obscure or cut off text or other parts of the UI. Code should be visually complete, when possible.
  • Disable irrelevant extensions that would alter the look of VS Code from what users would otherwise have on a fresh install, unless we are discussing extensions, etc.
  • Avoid unusual states in our UI that are not relevant to the subject matter and could be distracting or confusing (such as indicators for unsaved/uncommitted code, linting squiggly lines in the editor, selected text, breakpoints, open panels that aren't needed like find/replace or console/output).
  • Simplest code possible to convey a concept and avoid creating a distraction

Be consistent

  • Use the default dark theme, unless when discussing themes or concepts that warrant using a different theme
  • Use zoom level 1, unless there is an explicit need to zoom in or out
  • Use the same VS Code window size.

Screenshot filename rules

  • Image filenames use all lowercase and use dashes (-) as word separator. For example: ![Debug Breakpoints](images/debugging/breakpoints-view.png)
  • Use relative path names to link to an image (path and filename are case-sensitive!)
  • Don't update images in-place because they are cached on the server for indeterminate time. Create a new file and add a version indicator (e.g. yyyymmddseq) to the image filename.

Screenshot checklist

  • Display scaling is 100% (Windows), Default (macOS).

  • Use native monitor resolution.

  • Set the VS Code window size to 1600px wide (FYI, on retina double the size will be captured, no problem!).

    Tip: in Developer Tools console, type window.resizeTo(1600,1000), or use a utility like Sizer (Windows).

  • Set VS Code window zoom level to 1 ("window.zoomLevel": 1)

  • Use default dark theme.

  • Use default fonts.

Tip

Create a dedicated VS Code profile for taking screenshots.

Clone this wiki locally