Further down the line, documentation will always matter.

Further down the line, documentation will always matter. Build • Océane Franc • 06/09/21 • 7 min read

When I started studying technical writing at university, and later, when I became a professional technical writer, I came across a lot of various content: Reference guides, Release notes, UX documents, User manuals, Architecture documentation, Changelogs, SOPs, Internal Specs and APIs... to name a few.

A question quickly popped into my head: “How can a human being keep all that precious information organized, up to date and easily accessible for the client? That’s nearly impossible.” Little did I know that coming up with solutions for these issues would end up becoming one of the biggest challenges of my career.

Scaleway Documentation: when change is what we need.

To me, Scaleway Documentation was like a water bug suspended on the surface of a pond. First, enjoying the open space, the coolness of the water and the freedom of its movements. Then, summer came. The pond became swamped by other little bugs and what once was a nice little place to hang turned into a soupy turmoil where finding its way in or out was nearly impossible.

With that metaphor in mind, think of Scaleway technical documentation. While we keep launching great products, the volume of documentation has increased tremendously in the last year. As a result, finding the right documentation had become a fool’s errand. Even though what you are looking for exists, you end up spending too much time looking for it. In that big pool of content, we were lacking organization, architecture, tags, filters and a proper search bar.

Scaleway documentation represents 70% of the written content of the Scaleway website overall and for several years in the row, some of our documentation pages are the most visited industry. As a result, the urge to put the spotlight back on the documentation was crucial.

Where to start? The easiest part was to decide whether we would start off with a completely new project or try to improve what we had. And we all know that there's nothing more fun than being in a room with a whiteboard, a ton of post-its, a huge pack of markers, and a team of your most talented colleagues and collaborators. And this is what we came up with:

A simple and logical navigation structure

A good documentation website is a place where you can easily find what you are looking for. This could be via the search bar, the menu, the table of contents - anything that will allow you to solve your problem quickly.

With the new Scaleway documentation , we made all the content skimmable . The menu is organised into categories, each divided into products. The left side menu of the doc site and the console match each other in structure, giving more clarity for the user.

Under each product, you will find different types of content, each serving a different purpose : Concepts, Quickstarts, How-tos, Tutorials, APIs/CLI, Reference content, Troubleshooting and Videos . Always in that order to avoid ambiguity.

The content of a page itself uses clear headings, numbered lists, bulleted lists, links, info cards with colors, icons and code blocks with syntax highlighting and the copy-code option.

In addition, you can follow a real user path with the previous and next button at the end of each page. Don’t know what to do once you have modified your billing information ? Maybe creating billing alerts can be interesting to you.

The documentation navigation becomes simple, comprehensive and nearly universally-applicable.

Content to empower our users

I cannot stress this enough, but a piece of software without documentation is worthless. Product documentation is something that must be written and maintained. Indeed, as soon as a modification is made on a product or a feature, the documentation is impacted and should be edited consequently.

Therefore, we spent a few months reading, editing, testing, deleting and rewriting over 525 markdown files to ensure that what we would publish was accurate, detailed and simple to follow.

Power of visuals

As cliché as it might sound, a picture really is worth a thousand words. As such, we managed to create a few video tutorials to show you how to create your account or launch an Instance . A video tour of the console is also available to witness how smoothly you can use any Scaleway products, from Kubernetes to VPC .

However, we decided to go easy on the screenshots as we update the Scaleway Console every single day with improvements, bug fixes or feature updates. We wanted to keep the content as up-to-date as possible which meant using fewer screenshots. Isn't it frustrating to have a procedure that shows one thing when you see totally something else on your screen? Been there, done that.

Peer reviews

Documentation that is easy to contribute to is also easy to keep updated . We aim to deliver value as well as relevant information. We decided to empower our users to open Pull Requests to update or suggest new content themselves.

Scalers and external users follow the exact same rules. Please read the writing guidelines convention s prior your edits. Once done, perform the following:

Open your terminal and clone the docs-content repository . git clone git@github.com:scaleway/docs-content.git CopyContentIcon Copy code

Create a new branch. All branch names must comply with the following naming convention: [source]-[action]-[product] .

Source : Either int (for internal contributor) or ext (for external contributor) to Scaleway. If you are not a Scaleway staff member, please use ext.

Action : The action you will perform in the documentation you wish to work on, described in 3 letters or less. Example: add , rm or fix .

Product : The name of the product that corresponds to the documentation page you will edit.So in the branch ext-add-instances , an external contributor will add information to a documentation page of the Instances product category.

git checkout - b ext - add - instances CopyContentIcon Copy code

Make your edits on your branch using a text editor of your choice.

Add your changes (new or modified files) to the index. This command can be performed multiple times before a commit. In case you add multiple files, they must be separated by a whitespace. git add FILENAME FILENAME FILENAME CopyContentIcon Copy code OR git add -- all CopyContentIcon Copy code This command will automatically add all the files impacted by a change (creation and deletion included).

Commit…