permalink | title |
---|---|
/CONTRIBUTING.md |
Contributing |
Anyone who has a GitHub account can contribute to the documentation content:
-
Users within the Scaleway organization can open pull requests directly in the docs-content repository.
-
External users (i.e. not part of the Scaleway organization) must fork the repository and open a pull request from the forked repository.
- You have Git installed
- You have a GitHub personal account
- You have installed yarn package manager
- You have Markdown and MDX syntax knowledge
- You have read the writing guidelines
- All rules below concern this repository.
- Any PRs which do not comply with the rules below will be rejected.
-
Clone the
docs-content
repository by following the cloning procedure below. -
Make sure you have identified the type of content that you want to write (e.g. tutorial, API/CLI documentation, additional content or troubleshooting).
-
Create your branch locally. All branch names must comply with the following naming convention:
[source]-[action]-[product]
.-
source
: Eitherint
(for internal Scaleway contributors) orext
(for external contributors). -
action
: The action you will perform in the documentation you wish to work on, described in 3 letters or less. Example:add
(for adding content),rm
(for removing content) orfix
(for when you wish to fix typos). -
product
: the name of the product that corresponds to the documentation page you will edit.
ℹ️ Example:
in the branchint-add-instances
, an internal contributor will add information to a documentation page of the Instances product category. -
-
Make your edits to the documentation. Refer to the writing guidelines below to ensure your changes comply with our style guide.
-
Run
git commit -m "type(module): description with some words <BRANCH_NAME>"
. Refer to the commit naming conventions below to properly name your commit. -
Run
git push --set-upstream origin <YOUR_BRANCH_NAME>
, and go to the pull requests page to open a pull request.All PR names must comply with the following naming convention:
docs($PRODUCTNAME): $FIXEXPLANATION BRANCHNAME
.
All PRs are reviewed and approved by the Scaleway Product Documentation team before being merged by them.
- All rules below concern this repository.
- Any PRs which do not comply with the rules below will be rejected.
-
Access the docs-content repository, and click Fork in the top right corner. A form appears.
-
Keep the default values in the form, and click Create Fork.
-
Make sure you have identified the type of content that you want to write (e.g. tutorial, API/CLI documentation, additional content or troubleshooting).
-
Create your branch locally. All branch names must comply with the following naming convention:
[source]-[action]-[product]
.-
source
: Eitherint
(for internal Scaleway contributors) orext
(for external contributors). If you are not a Scaleway staff member, useext
. -
action
: The action you will perform in the documentation you wish to work on, described in 3 letters or less. Example:add
(for adding content),rm
(for removing content) orfix
(for when you wish to fix typos). -
product
: the name of the product that corresponds to the documentation page you will edit.
ℹ️ Example:
in the branchext-add-instances
, an external contributor will add information to a documentation page of the Instances product category. -
-
Make your edits to the documentation. Refer to the writing guidelines below to ensure your changes comply with our guidelines.
-
Run
git commit -m "type(module): description of what you performed <BRANCH_NAME>"
. Refer to the commit naming conventions below to properly name your commit. -
Run
git push --set-upstream origin <YOUR_BRANCH_NAME>
, and go to the pull request page of the forked repository to open a pull request. -
Click Create pull request, then select
-
base repository:
scaleway/docs-content
-
base:
main
-
head repository:
<your-account>/docs-content
-
compare:
<your-branch-with-changes>
-
Click Create pull request.
All pull requests names must comply with the following naming convention:
docs(<PRODUCT_NAME>): <ACTION> <EXPLANATION> <BRANCH_NAME>
.
All pull requests are reviewed and approved by the Scaleway Product Documentation team before being merged by them.
You have to clone the project locally to work on it.
- Copy the following code and enter it in your terminal:
git clone git@github.com:docs-content.git | bash -s -- cd docs-content && yarn
- Ensure
yarn
has been run, if not runyarn install
.
Helpful pre-commit commands:
yarn check-slugs
Output slugs that are not kebab-case well formatted.
This project uses conventionalcommits based on the Angular convention.
Here is a commit template example:
type(module): description with some words PROJECT-XXX
Lowercase only, (module)
is optional. Adding the project number at the end is recommended.
Here is the list of type
to use (commons in bold):
docs
- Do not use other than project docs itself concerns (like README file)
feat
- Add new materials (page, sections, …)
fix
- For instance, fix typos, images, …
refactor
- In rare cases, for instance if you have to change folders structures.
revert
- Oops case, if you want to redo previous history state
style
- For simple format changes that are not content changes
feat(console): add vpc how-to page MTA-2342
fix(iot): wrong image in quickstart
style: add bold at scaleway name occurrences MTA-1337
Markdown is a lightweight markup language for creating formatted text using a plain-text editor.
Files with markdown content usually use the .md
extension.
As we need to use evolved dynamic and designed blocks, for the Scaleway Documentation platform, the choice was to use the extended markdown format, with a special .mdx
extension.
With MDX files traditional markdown content can be used with React components.
MDX components are useful for adding rich content and interactions within your contributions.
This section shows code details listed on a full page.
🔎 See the full Components page.
Feel free to explore this page in your markdown editor to see how the components were used, or in .mdx
content files that already use MDX components.
Any Markdown file that contains a YAML frontmatter block will be processed by Gatsby as a special file.
The front matter must be the first thing in the file and must take the form of a valid YAML set between triple-dashed lines.
Here is a common example used in our .mdx
files:
---
meta:
title: How to create a Bare Metal server
description: This page explains how to create a Bare Metal server
content:
h1: Bare Metal server
paragraph: This is a tutorial Bare Metal
hero: assets/scaleway-account.png
tags: compute baremetal bare metal cloud server dedicated
dates:
validation: 2021-06-22
posted: 2020-03-12
---
Here starts the content…
meta
part is used for SEOtitle
anddescription
, it doesn't appear inside the websitecontent
part which containsh1
andparagraph
is used for title and description inside website pages.h1
is used as H1 in pages, in the HTML head element as the browser tab title and for SEO.paragraph
is used in pages and in the head element for SEO.image
is used for the hero section image in tutorial pages. The image path can be relative to the file.tags
are used to help populate search result lists or pages top.dates
are shown on pages under titles.validation
must be a date later than theposted
. Its format should beAAAA-MM-DD
.
In this section, point out what the user must have already prepared before starting the step-by-step. Include links to other documentation pages.
Example:
Requirements
- You have a Scaleway Account
- You have configured your SSH key
See also: Message boxes typographical conventions
You can go up to 5 hierarchy levels (H1, H2, H3, H4, H5).
Important
-
In the right menu, only H1 and H2 are visible.
-
No titles should be orphaned. For example, if you started with H2, you should go down in sequence. So the next step should either be another H2 or a level lower (in this case, H3).
See also: Anchors and titles components
At Scaleway we use US English.
What should be capitalized:
- Product names
Bold text is used to represent where a user should click or highlight other text relevant to the UI.
Example:
Click + Create an Instance to proceed.
Use a code block for examples of:
- commands
- scripts
- outputs
Use inline code when you need to reference information in your text, such as:
- environment variables
- e-mail addresses
- referencing parts of the code block in the text
Message boxes help you highlight important or pertinent information.
Tip: An alternative way of doing the step, or links to additional information about the step.
Note: Information about the consequence(s) of a step.
Important: Warning about a possible unwanted consequence (eg delete all data) or possible mistake that could be made during this step.
Requirements: A list of what the user must have already prepared before starting the step-by-step.
See also: Message box components
When referring to API calls or CLI commands, follow the environment variable conventions listed on this page. Use the same format for other variables.
Example:
$EMAIL_ADDRESS
If you need to use an example of IP addresses, some IP ranges are reserved for documentation:
IPv4
192.0.2.0/24
198.51.100.0/24
203.0.113.0/24
233.252.0.0/24
IPv6
2001:db8::/32
Save screenshots in .png
format.
Omit any personal information (such as e-mail addresses, addresses, telephone numbers, the Scaleway resource ID, etc). Use the blur effect over the information you wish to conceal.
If the image contents are already being described in the documentation text, there is no need to include a caption. To increase accessibility, if new information is being presented in the image, include a description (alt="caption"
).
Start with “Scaleway” and make the name as explicit as possible, describing the screenshot.
Example:
scaleway-top-right-menu.png
or scaleway-leave-organization