mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 17:31:56 +03:00
01c6bfdc8b
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/8510 Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com> GitOrigin-RevId: e46c7923dcf1bdad04a9025a38341cc729d5ef70
138 lines
5.9 KiB
Plaintext
138 lines
5.9 KiB
Plaintext
---
|
|
title: Images
|
|
description: Style for images and screenshots in documentation
|
|
keywords:
|
|
- hasura
|
|
- style
|
|
- images
|
|
slug: images
|
|
---
|
|
|
|
# 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](https://chrome.google.com/webstore/detail/window-resizer/kkelicaakdanhinjdeammmilcgefonfh?hl=en) 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 <pre style={{ background: `#FC336D` }}>#FC336D</pre> 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](https://evernote.com/products/skitch) 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](https://www.screen.studio/) 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](https://support.iclasspro.com/hc/en-us/articles/218569268-How-Do-I-Disable-or-Clear-AutoFill-AutoComplete-Information-)
|
|
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`](https://ffmpeg.org/):
|
|
|
|
```bash
|
|
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:
|
|
|
|
```jsx
|
|
import Player from '@site/src/components/Player';
|
|
```
|
|
|
|
And then use it like this:
|
|
|
|
```jsx
|
|
<Player src="/img/<SUBDIRECTORY>/<FILENAME>.webm" />
|
|
```
|