Images

A picture says a thousand words. Try to use images and diagrams wherever you can if it will provide more clarity to the user.

Screenshots

Scale

• Screenshots should be captured at a browser viewport width of 1200px. This helps keep scaling consistent.
• You can use this Chrome extension to quickly set your browser viewport to 1200px
• Don't zoom in or out.
• When placed in situ in the documentation, the text in the image of a screenshot should closely match the text size of the page itself.

Cropping

• Leave 20px blank margins in-image around all four sides for breathability of the image.
• Crop only the logical contextual area for the feature that you are referencing. For example:
  • don't crop the whole screen UI if you are calling attention to only one small component on the page.
  • do crop the whole screen UI if it is contextual to what you are referencing.
• Make sure if you are cropping a smaller area or component that the user understands where to find it and its place in context within their workflow.

File type

• Use PNGs.
• PNGs will automatically be optimized when added to the pull request

File name

• Include the Hasura feature and version number in the screenshot name to make it easier to check when screenshots are outdated.
• Name the file with this structure: {{action-depicted}}_{{image-step-or-variation-number-if-needed}}_{{hasura-feature-depicted}}_{{hasura-feature-version}}.png
• eg: connect-database-google-cloud_step-2_console_2-7-1.png

Callouts, arrows and other screenshot markup

• Use hex color

  #FC336D
  for all image markup.
• Use rounded corners on callout blocks.
• Generally, if you want to show selecting something, use borders. If you want to show clicking on a button, use arrows.
• Don't make arrows unnecessarily long or short.
• Use step numbering of a number in a circle. Start count from 1, not array 0 notation.
• Use the Skitch markup app if possible.

Versioning

• Always add an :::info Note admonitions for new features detailing the version at which the feature is supported from.
• Make sure prior versions of documentation are properly kept.

Animated images

Animated images should be used sparingly and should be used to show a user how to perform a task.

Creating animated images

• We use a tool called ScreenStudio to create animated images.
• This is a paid tool; if you don't have access to it, please ask someone on the docs team to create the animated image for you.
  • If you ask for an animated image, please provide a detailed description of what you want to show in the animated image along with the steps you want to highlight.
• If you are creating an animated image, please follow the guidelines below.

Guidelines

• Use Google Chrome with the default dark theme.
• Your browser window should be set to 1200px x 900px.
• Ensure your bookmark bar is hidden.
• It also helps to disable autocomplete in the URL and search bars.
• Carefully and deliberately perform the steps you want to show in the animated image.
  • If needed, you can speed up the playback of your actions during editing.

Workflow

Recording and editing

• Create a new project in ScreenStudio.
• Utilize this background image for a consistent look:
• As you edit, ensure the camera doesn't zoom in and out constantly; deliberately select when you want to emphasize a particular area of the screen using the zoom tool.
• We speak from experience: ☝️ it helps to practice this a few times first!
• When you are done, export the video as an mp4.

Converting and compressing

All videos should be converted and compressed to the webm format before being added to the docs. This can be done using ffmpeg:

 ffmpeg -i <ORIGINAL>.mp4 -c vp9 -b:v 0 -crf 55 <DESIRED_FINAL_FILENAME>.webm

The -crf flag controls the quality of the video. The lower the value, the higher the quality. The default value is 23. The range is 0-63, with 0 being lossless and 63 being the worst possible quality. A value of 55 is generally considered to be a good balance between quality and file size.

Adding to the docs

Use the <Player /> component to add the video to the docs. The component takes the following props:

Prop	Type	Description	Required	Default
src	string	The path to the video file.	Yes
autoPlay	boolean	Whether the video should autoplay when the page loads.		true
loop	boolean	Whether the video should loop when it reaches the end.		true
muted	boolean	Whether the video should be muted.		true
playsInline	boolean	Whether the video should play inline.		true
showControls	boolean	Whether the video should show controls.		false

You can import the component inside any .mdx file like this:

import Player from '@site/src/components/Player';

And then use it like this:

<Player src="/img/<SUBDIRECTORY>/<FILENAME>.webm" />