NavigationContentFooter
Jump toSuggest an edit

Scaleway Documentation Guidelines

Reviewed on 07 August 2024

This document sets out the writing guidelines (style guide) for Scaleway Documentation, including grammar, formatting, and standardized terminology. These guidelines should be followed by both internal and external contributors when making additions to the Scaleway Documentation site.

  • For details on contributing to the Scaleway documentation as a user, see Write for the Community.
  • For writing guidelines for the Scaleway console, see the UX Writing Guide.
  • For Scaleway design and branding guidelines, see Ultraviolet.

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, fiberCentre, fibre
Recognize, prioritizeRecognise, prioritise
Favorite, colorFavourite, 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 TYPEDESCRIPTION
How toShows 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
QuickstartShows how to do the main series of actions necessary to start using a Scaleway product via the console, e.g. Instances Quickstart
ConceptsDefines and briefly explains the main terminology associated with a Scaleway product, e.g. Kubernetes Concepts
TroubleshootingGives solutions to help resolve a common issue with a Scaleway product, e.g. VPC auto-config is not working
API/CLIPresents 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 ContentProvides detailed information on specific subjects and features associated with a Scaleway product, e.g. Optimize your Object Storage performance
TutorialExplains 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
FAQGives 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 TYPEDESCRIPTION
MetadataAt 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.
IntroductionA 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.
RequirementsBullet 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 bodyThe 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.
Tip

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

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

BAD

  1. Start by clicking Instances in the Compute section of the Scaleway console.
  2. You will see the Instances dashboard.
  3. 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 «Unlink Icon» 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.

Use native Markdown syntax for links:

Markdown syntaxRenders 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 pageFind more information here
See the API documentation for more detailsSee 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.

SyntaxRenders as
Use the toggle <Icon name="toggle" /> to activate the featureUse the toggle «Toogle Icon» to activate the feature

See the full list of available icons.

Messages

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

Message typeUse forSyntaxRenders as
NoteExtra information that may not be relevant in all cases or to all users<Message type="note"> </Message>
Note This is a note
TipInformation about a different way to accomplish something, or how to go further<Message type="tip"> </Message>
Tip This is a tip
ImportantCritical warnings and information that the user must read to avoid unwanted consequences or mistakes<Message type="important"> </Message>
Important This is important

Read more about message box components.

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

Read more about the tab component.

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 autobackupFeatures 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 snapshotsYou can create up to 9 snapshots.
A maximum of 5,000 samplesA maximum of 5.000 samples
A maximum of five thousand samples
A maximum of 5000 samples
Half of 1 is 0.5Half of 1 is 0,5
There are over 3 million usersThere 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 hourThe 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,000The 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:
TermAbbreviationExample
megabyteMBMemory: 100 MB
gigabyteMBMemory: 1 GB
gigabitnoneConnectivity; up to 10 gigabit
gigabits per secondGbpsBandwidth: 1 Gbps
megabits per secondMbpsBandwidth: 100 Mbps
gigabit-secondsGB-sStorage: 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 elementScreenshot
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

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: