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.
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.
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.
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
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
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.
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.
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.
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.
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.
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.
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
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«Unlink Icon» 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«Unlink Icon» next to the flexible IP address you want to detach.
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.
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.
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.
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.
<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.
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.
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: