Skip to main content

Contribute to Documentation

Documentation guideline​

Here's the guideline/conventions to follow for the Wazo documentation. Wazo documentation is generated with GatbsyJS. The source code is available on GitHub

Language​

The documentation must be written in english, and only in english.

File structure​

File and Folders​

  • Word should be separate by dashes (ex: /my-folder/my-file.md)
  • Don't use dot (.)

Images​

  • Should be stored in /static/images/uc-doc/
  • Should reproduce page path /static/images/uc-doc/page1/subpage2/myimage.jpg

Content​

Documentation content should be stored in /content/uc-doc/.

Table of Contents​

The table of contents is based on files and folders structure on /content/uc-doc. If you want to create a new level you must :

  • Create a new folder
  • Add an index.md with a list of subpages (Required to generate a clean navigation)
  • Create a new file mypage.md
  • Write your content inside the new file

Headings​

  • The top section of each file must be capitalized using the following rule: capitalization of all words, except for articles, prepositions, conjunctions, and forms of to be.

    <!-- Correct -->
    The Vitamins are in My Fresh California Raisins

    <!-- Incorrect -->
    The Vitamins Are In My Fresh California Raisins

  • Must use # syntax to create a title

  • Must be H2 or lower. (H1 titles are automatically generated by React)

    ## My Title 1

    ### My Subtitle 1.1

    ## My Title 2

Anchors and Headings​

  • Default: are automatically generated based on the title text
  • Custom: words must be separated by dashes
## My Title \{#title-custom-anchor}

Lists​

Bullet lists:

- First item
- Second item
- ...

Autonumbered lists:

1. First item
2. Second item
3. ...

Code blocks​

To highlight code, you can add the following values at the code block initialization. It's better to specify it because it will improve readability.

  • shell
  • Shell
  • YAML
  • Python
  • Javascript
  • Markdown
  • ini

Others​

  • There must be no warning nor error messages when building the documentation with yarn start.
  • There should be one and only one newline character at the end of each file.
  • There should be no trailing whitespace at the end of lines
  • Paragraphs must be wrapped and lines should be at most 100 characters long
  • You must run yarn format:uc-doc when you're done