Scaleway Documentation Guidelines

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:

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.

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:

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:

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.

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.

Links

Use native Markdown syntax for links:

• 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.

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

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

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.

See the full list of available icons.

Messages

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

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:

• Tab one
• Tab two
• Tab three

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”.

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).

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)

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)

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:

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.

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

Before you start

To complete the actions presented below, you must have:

• 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:

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: ...).

Frequently used requirements