Skip to content

Style Guide

Jump to bottom
Nick Trogh edited this page Feb 24, 2026 · 10 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.

Feature videos

Video content rules

Include only what matters

  • Remove anything that's not part of the feature being demonstrated, such as the primary sidebar or unrelated editors.
  • Be mindful of sensitive information you don't want to show, such as email addresses, API keys, or other personal data. Cut them out in post-production if needed.
  • Hide language models that are not publicly available.
  • Use a relatable user scenario to demo the feature. This helps viewers understand how the feature fits into their workflow.

Be consistent

  • Display scaling is 100% (Windows), Default (macOS).
  • Use a consistent VS Code window size of 1600px wide.
  • Set VS Code zoom level to 1x or 2x, depending on how much content needs to be shown.
  • Use the default dark theme and fonts.

Recording tips

  • Enable screencast mode. Useful if the highlighting mouse clicks is useful. Disable when you typing is involved.
  • Use copy-paste instead of manual typing. Unless typing itself is the feature being demonstrated.
  • Don't move the cursor unnecessarily. This helps in post-production for trimming pauses and unnecessary scenes.
  • Rehearse!. But record your rehearsals. Sometimes trimming is the only thing needed to turn a rehearsal into a great video.

Editing and post-production

  • Trim the video to only what is needed to showcase the feature.
  • Keep the video length below 30 seconds. You can usually trim a lot of noise and pauses.
  • When you have a long spinner, cut out the middle part or speed up that section in post-production.

Video checklist

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

  • VS Code window size is 1600px wide.

  • VS Code zoom level is 1x or 2x.

  • Use default dark theme and fonts.

  • Remove UI elements not related to the feature.

  • No sensitive information visible (email, API keys, etc.).

  • Non-public language models are hidden.

  • Video is trimmed and under 30 seconds.

Tip

Create a dedicated VS Code profile for screenshots or demo videos.

Clone this wiki locally