Overall writing guidelines

Language

Scaleway Documentation uses American English (US English). Where words are spelled differently in American English to, for example, British English, use the American spelling. Here are some examples:

✅ AMERICAN ENGLISH	❌ OTHER VARIATIONS
Center, fiber	Centre, fibre
Recognize, prioritize	Recognise, prioritise
Favorite, color	Favourite, colour

We do not accept contributions to Scaleway Documentation in languages other than English.

Tone

The tone of Scaleway Documentation is generally formal. Do not use the passive voice, "please" or "thank you", the future tense or contractions.

✅ DO WRITE	❌ DO NOT WRITE
Click DELETE to delete the Instance.	The Instance is deleted by clicking DELETE.
Tick the box to accept the conditions.	Please tick the box to accept the conditions.
Select Metrics. The Grafana dashboard opens.	Select Metrics. The Grafana dashboard will open.
You cannot leave the field empty.	You can't leave the field empty.

Consistency

We aim for the highest possible level of consistency in the documentation when it comes to the application of these guidelines, and particularly:

The wording used when referring to Scaleway products and features
The structure and formatting of our documentation pages
The correct use of grammar and syntax

Inconsistency can result in confusion and misinterpretation, while documentation that applies consistent standards provides a streamlined user experience, and underlines the professionalism and reliability of Scaleway.

Page types, formats and structure

Page types

All documentation pages must fall into one of the following categories:

PAGE TYPE	DESCRIPTION
How to	Shows how to do a core action (e.g. create, configure, delete, use features) for a Scaleway product via the console, e.g. How to create a Load Balancer
Quickstart	Shows how to do the main series of actions necessary to start using a Scaleway product via the console, e.g. Instances Quickstart
Concepts	Defines and briefly explains the main terminology associated with a Scaleway product, e.g. Kubernetes Concepts
Troubleshooting	Gives solutions to help resolve a common issue with a Scaleway product, e.g. VPC auto-config is not working
API/CLI	Presents information and tips for creating and configuring a Scaleway product via both official and third-party APIs, CLIs, SDKs and other developer tools, e.g. Terraform, e.g. Using Object Storage with the AWS-CLI. These pages complement the main developer reference documentation.
Additional Content	Provides detailed information on specific subjects and features associated with a Scaleway product, e.g. Optimize your Object Storage performance
Tutorial	Explains how to use a Scaleway product with a third-party tool, or how to use multiple Scaleway products together for a specific use-case, e.g. Deploying Strapi on an Instance
FAQ	Gives answers to the most frequently asked questions about Scaleway products, e.g. Cockpit FAQ

Anyone can suggest corrections, improvements and extensions to any type of documentation page by forking our repository and opening a PR.

When creating an entirely new documentation page from scratch, we generally expect external contributions to be for new Tutorials, Additional Content, Troubleshooting or API/CLI pages. The Scaleway Documentation team handles the creation of new How to, Quickstart, Concepts and FAQ pages.

Page format

All Scaleway documentation pages should be .mdx files (MDX is an extension to Markdown that lets you include JSX). Any images included within the page must be .webp files.

Page structure

Scaleway Documentation pages should conform to the following structure:

PAGE TYPE	DESCRIPTION
Metadata	At the top of the page, used for indexing, search and the generation of the page title (H1). The `dates` section is crucial for tracking and displaying when pages were first created and last updated.
Introduction	A few sentences (or short paragraphs), that briefly explain the purpose of the documentation and give any necessary preliminary information. This will be displayed in search results for the page in Scaleway's internal search engine.
Requirements	Bullet points stating what the user must already have accomplished before starting any instructions on this documentation page. Necessary for How tos, Quickstarts and Tutorials. May not be relevant for other page types, e.g. FAQ, Concepts.
Page body	The content depends on the page type. Split long pages into subsections with headers. Always use numbered lists when explaining steps a user should take. See also page content

If you are creating a new page, it may be easiest to duplicate an existing page and adapt it to your requirements. See the raw files on our GitHub repo for this purpose, for example this tutorial.

More information about the different sections of each page can be found by following the links in the table above.

Page content

Headers

There can be only one H1 on each page (the page title, defined in the metadata)
Use H2s (e.g. ## My subtitle) to divide the page into subsections, and H3s (e.g. ### My sub-subtitle) to divide the subsections (if appropriate). You can go up to 5 hierarchy levels (H5). In the right "Jump-to" menu, only H2s and H3s are visible and clickable.
Headers also serve as anchors. Link to a header anchor as follows [text to display](#header-with-spaces-replaced-by-dashes)
No headers should be orphaned. If you begin with H2, go down in sequence. The next step should either be another H2 or a level lower (in this case, H3).
All headers should be in sentence case. Product names should nonetheless be capitalized as appropriate.

Numbered steps

When explaining to a user what to do, use numbered steps.

Each step should represent one action the user must do.
Each step should start with an imperative verb.
If you want to explain the effect of the action, do so in a sentence at the end of the numbered step, or on a new, non-numbered indented line.

If you are including an image, code block, or any "new line" element as part of a numbered step, it must be indented by two levels compared to the numbered step. This is to prevent the numbered list from "breaking" and resetting to zero when the page renders.

✅ GOOD

1. Create a new text file called `requirements.txt`.
2. Copy and paste the following code into the file:
    ```
    numpy==1.21.6
    tinyhtml==1.2.0
    ```
3. Save and exit
4. Ensure that your file structure is in line with the following image:
    <Lightbox src="scaleway-file-structure.webp" />
5. Click **Launch**

✅ GOOD

Click Instances in the Compute section of the Scaleway console. The Instances dashboard displays.
Click the Instance whose flexible IP address you want to detach. The Overview page for that Instance displays.
Click Detach next to the flexible IP address you want to detach.

❌ BAD

Start by clicking Instances in the Compute section of the Scaleway console.
You will see the Instances dashboard.
Next, you need to find the Instance whose flexible IP address you want to detach, and click on it. You'll see the Overview page for the Instance. To finish the process, click Detach next to the flexible IP address you want to detach.

Code blocks

Put code snippet into code blocks, using the triple backspace character. Specify the language of the code block, using a supported language.

Markdown syntax:

```python
my_list=[1,6,9,4]
my_list[1]=3 
print(my_list)
```

Renders as:

my_list=[1,6,9,4]
my_list[1]=3 
print(my_list)

Inline code

Use inline code to reference information in your text, such as environment variables, placeholder values, and single-line short code snippets.

Markdown syntax (backticks):

Do not forget to replace `<YOUR INSTANCE NAME>` with the name of your Instance.

Renders as:

Do not forget to replace <YOUR INSTANCE NAME> with the name of your Instance.

Links

Use native Markdown syntax for links:

Markdown syntax	Renders as
`Open the [Scaleway console](https://console.scaleway.com/)`	Open the Scaleway console

Include links to other Scaleway Documentation pages to:
- Avoid repeating instructions that already exist on an existing page
- Help the user find other useful and related content
- Link to concept definitions that may not be immediately comprehensible
Include links to external pages to:
- Help the user find third-party tools and resources that are mentioned in documentation
- Provide information that is not already contained within Scaleway Documentation. Favor sites such as Wikipedia, which are stable, neutral and open-source.

Avoid using link text such as here or this page. Prefer descriptive terms, while keeping link text concise.

✅ GOOD LINK TEXT	❌ BAD LINK TEXT
Find more information on the pricing page	Find more information here
See the API documentation for more details	See this page for more details

When linking to other Scaleway Documentation pages, use relative links. Include a leading slash and a trailing slash:

✅ GOOD INTERNAL LINK	❌ BAD INTERNAL LINK
`Refer to the [VPC Quickstart](/network/vpc/quickstart/)`	`Refer to the [VPC Quickstart](https://www.scaleway.com/en/docs/network/vpc/quickstart/)` `Refer to the [VPC Quickstart](/en/docs/network/vpc/quickstart/)` `Refer to the [VPC Quickstart](network/vpc/quickstart)`

When linking to a Scaleway Documentation page anchor, include a leading slash, but no trailing slash

✅ GOOD INTERNAL ANCHOR LINK	❌ BAD INTERNAL LINK
Anchor is on same page as link: `Learn more about [InstantApps](#instantapp)`	`Learn more about [InstantApps](https://www.scaleway.com/en/docs/compute/instances/concepts/#instantapp/)`
Anchor is on different page : `Learn more about [InstantApps](/compute/instances/concepts/#instantapp)`	`Learn more about [InstantApps](/#instantapp/)`

When linking to an external page, copy and paste the full link exactly as it appears in the browser (including any slashes as shown).

When writing a "fake" or example link that does not lead to a real page, put it in inline code by using backticks: `www/example-link.com`.

When including a "fake" or example link in a code box with an <a href> tag or similar, include the keyword URLexample in the URL:

```php
<?php
more code here
?>
 
To go to the next page <A HREF="URLexample/nextpage.php">click here</A>
```

Inline console icons

Use a console icon when referring in the documentation to the equivalent icon in the Scaleway console.

Syntax	Renders as
`Use the toggle <Icon name="toggle" /> to activate the feature`	Use the toggle to activate the feature

See the full list of available icons.

Messages

Three types of message boxes are available, to use as follows:

Message type	Use for	Syntax	Renders as
Note	Extra information that may not be relevant in all cases or to all users	`<Message type="note"> </Message>`	This is a note
Tip	Information about a different way to accomplish something, or how to go further	`<Message type="tip"> </Message>`	This is a tip
Important	Critical warnings and information that the user must read to avoid unwanted consequences or mistakes	`<Message type="important"> </Message>`	This is important

Tabs

You can use the tabs component to:

Explain different but equivalent ways to do something
Give instructions for multiple operating systems, environments, platforms or similar
Show conditional instructions, where the user must follow one set or the other depending on a condition

See an example of the tabs component in action on the How to connect to an Instance page.

Tabs syntax:

<Tabs id="example-tabs">
  
  <TabsTab label="Tab one">
    This is the content of tab one
  </TabsTab>
  
  <TabsTab label="Tab two">
    This is the content of tab two
  </TabsTab>
  
  <TabsTab label="Tab three">
    This is the content of tab three
  </TabsTab>

</Tabs>

Renders as:

This is the content of tab one This is the content of tab two This is the content of tab three

Grammar, syntax and typography

Pronouns

When addressing the user, say "you". When referring to Scaleway, say "Scaleway", "it", or "we".

✅ DO WRITE	❌ DO NOT WRITE
You can delete the Instance at any time.	The user can delete the Instance at any time.
Scaleway offers numerous Instance types.	The provider offers numerous Instance types

Capitalization

Always capitalize Scaleway product names (e.g. Instance, Load Balancer, Kubernetes Kapsule, Private Networks).

Do not capitalize names of product features (e.g. security group, bucket, snapshot), unless the feature name is a created word or phrase with a meaning specific to Scaleway, (e.g. InstantApp, Easy Deploy).

Titles and headers should be written in sentence case.

Bold text

Use bold text when explaining navigation of the different sections and buttons of the Scaleway console:

✅ Click Create Instance to proceed. ✅ The Edge Services dashboard displays.

Prepositions

Always use "click", not "click on"

✅ Click Create Instance to proceed. ❌ Click on the Create Instance button to proceed.

Commas

Use the Oxford comma (also known as the serial comma).

✅ DO WRITE	❌ DO NOT WRITE
Features include autoscale, autoheal, and autobackup	Features include autoscale, autoheal and autobackup

Numbers and figures

Numbers

Write numbers one to nine in full (e.g. "You have five Instances in your Organization").
Use numerals for numbers ten and above (e.g. "A maximum of 10 backend servers").
Use commas to separate thousands (e.g. 5,000 (five thousand), 250,000 (two hundred and fifty thousand))
Use periods to designate decimals (e.g. 0.5 (zero point five), 50.2 (fifty point two))
For amounts in millions or billions, use numerals and spell out million or billion (e.g. 1.5 billion, 3 million)

✅ DO WRITE	❌ DO NOT WRITE
You can create up to nine snapshots	You can create up to 9 snapshots.
A maximum of 5,000 samples	A maximum of 5.000 samples A maximum of five thousand samples A maximum of 5000 samples
Half of 1 is 0.5	Half of 1 is 0,5
There are over 3 million users	There are over 3,000,000 users There are over 3m users

Money

Put the currency sign before the numerals, with no space (e.g. €50)
Use a period to signify cents (e.g. €50.25)
Use commas to separate thousands (e.g. €3,000)

✅ DO WRITE	❌ DO NOT WRITE
The price is €0.11 per hour	The price is €0,11 per hour The price is 0,11€ per hour The price is 0.11€ per hour
The maximum charge is €150,000	The maximum charge is €150.000 The maximum charge is 150 000€

Dates and times

For times, use the 24-hour format. If it is necessary to use the 12-hour format, use a.m. or p.m. appropriately
For dates, use day/month/year or DD/MM/YY.
You can also write out the date, e.g. 14 January 2022. Avoid ordinals, e.g. 14th January. For a full list of allowed date formats, see the UX writing guide.

Bits and bytes

Add a space between the bits/bytes abbreviation and the number, e.g. 100 MB, 1 Gbps
Use the following abbreviations:

Term	Abbreviation	Example
megabyte	MB	Memory: 100 MB
gigabyte	MB	Memory: 1 GB
gigabit	none	Connectivity; up to 10 gigabit
gigabits per second	Gbps	Bandwidth: 1 Gbps
megabits per second	Mbps	Bandwidth: 100 Mbps
gigabit-seconds	GB-s	Storage: 1 GB-s

Wording and vocabulary

Environment variables

When citing Scaleway API or CLI commands, use the established environment variable conventions.

Console wording conventions

When referring to different aspects of the Scaleway console, use the following terms:

Console element	Screenshot
Side menu
Organization drop-down menu
$PRODUCT_NAME dashboard, e.g. Object Storage dashboard
$PRODUCT_NAME creation page ( NOT `splashscreen`), e.g. Instances creation page
$PRODUCT_NAME creation wizard, e.g. Load Balancer creation wizard

Product and feature names

When referring to Scaleway products and features, follow the wording and capitalization that is used on the Scaleway console. See also the capitalization rules.

A wording handbook is available internally, with a full list of correct product and feature naming. Contact a member of the Scaleway Documentation team for more details.

Images

Lightbox component

Use the Lightbox component for images, with the following syntax:

<Lightbox src="scaleway-image-descriptor.webp" alt="description of image" />

All images must be in webp format, and stored in the page's assets folder. Image names must always start with scaleway, and the words should be hyphen-seperated.

When to include images

It is appropriate to include some screenshots in documentation pages such as How tos, Quickstarts and Tutorials, to help orient the user and provide visual cues to help them correctly carry out the given steps. However, screenshots require significant effort to maintain over the long term, and slow down the loading times of the documentation site. We therefore recommend including screenshots when needed as a "location anchor" for users, but not for every step in a series.

Screenshot guidelines

Blur out any personal information (such as email addresses, telephone numbers, IDs)

If you need to refer to different specific parts of a screenshot in the documentation, annotate it with circled letters or numbers in an appropriate Scaleway brand color and font:

Diagrams and schemas

Diagrams and schemas should be produced in accordance with Scaleway visual design guidelines and assets. These are only available internally: contact a member of the Scaleway Documentation team.

Additional examples and guidance

Metadata

---
meta:
  title: How to create an Instance
  description: Learn how to create a cloud instance with Scaleway in simple steps. Follow this guide to efficiently set up and manage your compute resources.
content:
  h1: How to create an Instance
  paragraph: Learn how to create a cloud instance with Scaleway in simple steps. Follow this guide to efficiently set up and manage your compute resources.
tags: instance create
dates:
  validation: 2024-06-10
  posted: 2021-05-26
categories:
  - compute
---

meta: title and meta: description: The title and description of the page, used by external search engines when indexing and displaying results. The description should be between 120 and 160 characters, and SEO-optimized, using clear, engaging language suitable for a wide audience.
content: h1: The main title that displays on the documentation page.
content: paragraph: The description that displays on some documentation pages (e.g. when the page is linked to from a product card.
tags: The tags used by internal and external search engines to help users find the page
dates: posted: The date the page was originally created, in the format yyyy-mm-dd. This displays on the generated page.
dates: validation: The date the page was last validated, in the format yyyy-mm-dd. This displays on the generated page, and is used by the Documentation team when identifying documentation pages that need reviewing.
categories: The overall product category that the documentation fits into, used by the site's internal Algolia search.

The `meta: title` and `content: title` should be the same, other than in exceptional cases. Titles should be in [sentence case](https://en.wikipedia.org/wiki/Letter_case#Sentence_case). Different page types should have different types of titles: - **How to**: How to + infinitve verb + 5 words maximum - **Tutorial**: Start with a gerund, e.g. "Deploying WordPress with LEMP on Ubuntu Focal Fossa" - **Troubleshooting**: The title should describe the problem, e.g. "Auto-configuration is not working" - **Additional Content**: The title should either be in noun form, e.g. "Security and Reliability", or gerund, e.g. "Understanding the autohealing feature"

Introduction

In this tutorial, you will learn how to use **Loki** and **Grafana** to collect your Kubernetes logs on a [Kapsule cluster](/containers/kubernetes/how-to/create-cluster/).

Loki is a log aggregation system inspired by **Prometheus**. It is easy to operate, as it does not index the content of the Kubernetes logs but sets labels for log streams. Your metadata (object labels) can be used in Loki for scraping Kubernetes logs. If you use Grafana for metrics, Loki will allow you to have a single point of management for both logging and monitoring.

The introduction should be a few sentences, or a few short paragraphs, which explain the purpose of the documentation, and why it may be of interest to users. Briefly explain any third-party products or key features. Include links to other relevant pages where necessary.

Requirements

A Scaleway account logged into the console
Owner status or IAM permissions allowing you to perform actions in the intended Organization
Created a Kapsule cluster
Configured kubectl on your machine
Installed helm (version 3.2+), the Kubernetes packet manager, on your local machine

Start by using the macro <Macro id="requirements" /> or type the macro text manually. For example:

Macro id	Text formatting
`<Macro id="requirements" />`	## Before you start To complete the actions presented below, you must have:

Continue by listing the necessary products, resources or items users must have. Remember to start each item in a way that it forms a coherent sentence when combined with the intro macro (To complete the actions presented below, you must have: ...).

DO WRITE ✅	DO NOT WRITE ❌
## Before you start To complete the actions presented below, you must have: - A Scaleway account logged in to the console - An SSH key - A valid API key	To complete the actions presented below, you must have: - You have a Scaleway account - Have an SSH key -SSH key

Frequently used requirements

MDX formatting	What users see
`- A Scaleway account logged in to the [console](https://console.scaleway.com)`	- A Scaleway account logged in to the console
`- [Owner](/identity-and-access-management/iam/concepts/#owner) status or [IAM permissions](/identity-and-access-management/iam/concepts/#permission) allowing you to perform actions in the intended Organization`	- Owner status or IAM permissions allowing you to perform actions in the intended Organization
`- An [SSH key](/identity-and-access-management/organizations-and-projects/how-to/create-ssh-key/)`	- An SSH key
`- A valid [API key](/identity-and-access-management/iam/how-to/create-api-keys/)`	- A valid API key
`- Downloaded and installed the [Scaleway CLI](https://github.com/scaleway/scaleway-cli#scaleway-cli-v2)`	- Downloaded and installed the Scaleway CLI
`- An [Instance](/compute/instances/how-to/create-an-instance)`	- An Instance

Files

guidelines.mdx

Latest commit

History

guidelines.mdx

File metadata and controls

Overall writing guidelines

Language

Tone

Consistency

Page types, formats and structure

Page types

Page format

Page structure

Page content

Headers

Numbered steps

Code blocks

Inline code

Links

Inline console icons

Messages

Tabs

Grammar, syntax and typography

Pronouns

Capitalization

Bold text

Prepositions

Commas

Numbers and figures

Numbers

Money

Dates and times

Bits and bytes

Wording and vocabulary

Environment variables

Console wording conventions

Product and feature names

Images

Lightbox component

When to include images

Screenshot guidelines

Diagrams and schemas

Additional examples and guidance

Metadata

Introduction

Requirements