Updating readme, contributing and docs-guideline files

Author: Y0Coss

CONTRIBUTING.md

@@ -1,11 +1,10 @@
-# How to contribute to OVH documentation
+# How to contribute to OVHcloud documentation
 
 ## Contribute guidelines
 
 All our documentation is written using markdown slightly customized. You can find all details on the repository sort [here](docs-guideline/docs-guideline.md) and info on our customized markdown [here](docs-guideline/markdown-custom.md).
 
-All docs appear on <https://docs.ovh.com>.
-
+All docs appear on <https://help.ovhcloud.com/csm>.
 
 ## How to contribute
 
@@ -16,12 +15,12 @@ For example : FR Update Change email password. Product shortcut can be added if
 
 ### Pull Request Reviews
 
-All pull requests are reviewed by our Technical Copywriter team to ensure that our guide style is respected and that all technical information are correct. Your pull request won't be merged immediately, each request will be reviewed. So changes may apply when merged is done.
+All pull requests are reviewed by our Technical Copywriters team to ensure that our guide style is respected and that all technical information are correct. Your pull request won't be merged immediately, each request will be reviewed. So changes may apply when merged is done.
 
-Once validated by our reviewers, the request will be merged and the updated doc will be online. If online version doesn't suit to what you wanted when you applied, feel free to tell us.
+Once validated by our reviewers, the request will be merged and made public shortly after. If the online version doesn't suit your original needs, feel free to tell us.
 
-Our team will do his best to answer and deal with your request as fast as possible but don't forget that all requests are reviewed and it takes time.
+Our team will do their best to answer and deal with your request as fast as possible.
 
 ### License appliance
 
-When you ask for a change on OVH docs platform, you accept the [LICENCE](LICENCE) requirement.
+When you ask for a change on the OVHcloud documentation platform, you accept the [LICENCE](LICENCE) requirement.

docs-guideline/docs-guideline.md

@@ -5,7 +5,7 @@ ___
 
 ## Storage
 
-All guides are stored in this [repository](#)
+All guides are stored in this repository's [pages](https://github.com/ovh/docs/tree/develop/pages) folder.
 
 ### Repository structure
 
@@ -23,8 +23,8 @@ A `guide` belongs to a `product` that belongs to an `universe`. Keep this in min
 |   |   |   └── product.fr-fr.md (title: Domaines et DNS)
 |   |   ├── universe.en-gb.md (title: Web)
 |   |   └── universe.fr-fr.md (title: Web)
-|   ├── home.en-gb.md (title: OVH - Documentation)
-|   └── home.fr-fr.md (title: OVH - Guides)
+|   ├── home.en-gb.md (title: OVHcloud - Documentation)
+|   └── home.fr-fr.md (title: OVHcloud - Guides)
 └── README.md
 ```
 
@@ -44,7 +44,25 @@ _example_: `home.en-gb.md`, `universe.fr-fr.md`, ...
 
 #### content-types
 
-##### home
+##### index
+
+The [index.md file](https://github.com/ovh/docs/blob/develop/pages/index.md) introduced in December 2022 is the single source of truth for guides organisation on the public documentation website: <https://help.ovhcloud.com/csm>.
+
+There can be up to 3 categories levels in addition to the KB base level. The indentation is made in 4 spaces increments, and reflects the nesting structure of the guides and categories.
+
+The labels and titles are all in english. Translations of the L1 and L2 categories are listed in the `index-translations.<language>.yaml` files.
+
+The index is structured as such:
+
+```bash
+## Contents
++ Knowledge base
+    + [L1 category](full-slug)
+        + [L2 category](full-slug)
+            + [English title of the guide](repository-guide-path)
+```
+
+##### home (deprecated)
 
 Home page for a specific `zone` and `language` pair.
 No content in this file except metadata.
@@ -60,12 +78,12 @@ Add metadata as yaml frontmatter
 
 ```md
 ---
-title: OVH Documentation
+title: OVHcloud Documentation
 excerpt: How can we help you ?
 ---
 ```
 
-##### universe
+##### universe (deprecated)
 
 Page that lists all visible products the universe owns.
 No content in this file except metadata.
@@ -77,10 +95,10 @@ No content in this file except metadata.
 | title   | title of the product             | mandatory              |
 | excerpt | short desc of the universe       |                        |
 | slug    | part of the url                  | (default: folder name) |
-| order   | order of the universe in home    |                        |
+| order   | order of the universe in home    | deprecated             |
 | hidden  | not visible in home if True      | (default: False)       |
 
-##### product
+##### product (deprecated)
 
 Page that lists all visible guides the product owns.
 No content in this file except metadata.
@@ -104,15 +122,24 @@ Page containing documentation about the subject of your choice.
 | name    | description                      | extra                  |
 |---------|----------------------------------|------------------------|
 | title   | title of the doc                 | mandatory              |
-| excerpt | short desc of the doc            |                        |
-| slug    | part of the url                  | (default: folder name) |
-| section | product's section of the doc     | (default: Misc)        |
-| order   | order of the doc in section      |                        |
+| excerpt | short description of the doc     | mandatory              |
+| slug    | part of the url                  | deprecated             |
+| section | product's section of the doc     | deprecated             |
+| order   | order of the doc in section      | deprecated             |
 | hidden  | not visible in section if True   | (default: False)       |
 
+###### meta.yaml
+
+File containing mandatory unique identifiers for each guide.
+
+| name     | description                      | extra                  |
+|----------|----------------------------------|------------------------|
+| id       | V4 UUID                          | mandatory              |
+| full_slug| part of the url                  | mandatory              |
+
 ###### images
 
-If you want to add some pictures in your guide, create a folder images within your guide folder and place your pics there.
+If you want to add some pictures in your guide, create a folder images within your guide folder and place your images there.
 
 ```bash
 ...
@@ -124,7 +151,7 @@ If you want to add some pictures in your guide, create a folder images within yo
 ...
 ```
 
-You can now reference your pics relatively to your guide. See below an example for the file `my-super-guide/guide.en-gb.md`
+You can now reference your images relatively to your guide. See below an example for the file `my-super-guide/guide.en-gb.md`
 
 ```markdown
 ... ![image 02 alt](images/02.jpg) ...
@@ -137,40 +164,34 @@ Each guide must be placed in a folder with a representative name
 
 Allowed `ISO 639-1` language code (*[wikipedia](https://en.wikipedia.org/wiki/ISO_639-1)*)
 
-- `cs`: Czech
 - `de`: German
 - `en`: English
 - `es`: Spanish
-- `fi`: Finnish
 - `fr`: French
 - `it`: Italian
-- `lt`: Lithuanian
-- `nl`: Dutch
 - `pl`: Polish
 - `pt`: Portuguese
 
 #### zones
 
 Allowed `ISO 3166-1` country code (*[wikipedia](https://en.wikipedia.org/wiki/ISO_3166-1)*)
 
+- `asia`: Asia
 - `au`: Australia
 - `ca`: Canada
-- `cz`: Czech Republic
 - `de`: Germany
 - `es`: Spain
-- `fi`: Finland
 - `fr`: France
 - `ie`: Ireland
 - `it`: Italy
 - `gb`: United Kingdom
-- `lt`: Lithuania
-- `nl`: Netherlands
 - `pl`: Poland
 - `pt`: Portugal
-- `us`: United States
+- `sg`: Singapore
+- `us`: World English / World Spanish
 
 __Note__
-Exhaustiv list of authorized language suffixes: `cs-cz`, `de-de`, `en-au`, `en-ca`, `en-ie`, `en-gb`, `en-us`, `es-es`, `es-us`, `fi-fi`, `fr-ca`, `fr-fr`, `it-it`, `lt-lt`, `nl-nl`, `pl-pl`, `pt-pt`.
+Exhaustive list of authorized language suffixes: `de-de`,`en-asia`, `en-au`, `en-ca`, `en-ie`, `en-gb`, `en-us` (World English), `es-es`, `es-us` (América Latina), `fr-ca`, `fr-fr`, `it-it`, `pl-pl`, `pt-pt`.
 
 ___
 

readme.md

@@ -1,27 +1,16 @@
 # OVHcloud Documentation
 
-[![Build Status](https://travis-ci.org/ovh/docs.svg?branch=develop)](https://travis-ci.org/ovh/docs)
+This repository contains all the public documentation available about OVHcloud products, in all languages. A good way to find answers to some "how to" questions about OVHcloud products.
 
-Here is all public documentation available about OVHcloud products, in all languages. A good way to find answers to some "how to" questions about OVHcloud products.
-
-A web version also exists [here](https://docs.ovh.com); the website and this repo are synced.
+A web version also exists [here](https://help.ovhcloud.com/csm). This website and this repo are synced.
 
 This project is under active development, and new guides are added or updated on a daily basis.
 
-## Built With
-
-* [Grav CMS](https://getgrav.org/) - The editor used internally to produce and manage guides
-* [Algolia](https://www.algolia.com/) - The search engine used in docs.ovh.com
-
-## Test it
-
-* [docs-rendering-engine](https://github.com/ovh/docs-rendering) - Our HTML templating engine based on Pelican. ISO-rendering of docs.ovh.com
-
 ## Contributing
 
 We will be happy to take a look at your contributions. You can contribute to this project by updating some existing guides, completing them or creating new ones.
 
-A good way to easily get started with contributions is [to fork the ovh/docs repo](https://docs.github.com/en/free-pro-team@latest/github/getting-started-with-github/fork-a-repo), write your changes on your fork then [create a pull request (PR)](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-a-pull-request-from-a-fork) from your fork to the ovh/docs repo. Your PR must be done on the "develop" branch.
+A good way to easily get started with contributions is [to fork the ovh/docs repo](https://docs.github.com/en/get-started/quickstart/fork-a-repo), write your changes on your fork then [create a pull request (PR)](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) from your fork to the ovh/docs repo. Your PR must be done on the "develop" branch.
 
 Our guides editing team will then review your contribution and choose to edit, validate or reject it.