====== Documentation practices ======
  Describes documentation practices to create clear and consistent documentation
===== Disclaimer =====
  * Each page must start with a short disclaimer
  * Use short sentence and short lines (Small screen friendly), example:

  This features will help user figuring out problems
  Use it when you receive alarm notifications
===== Titles =====
  * Use title structures to organize content:
    * Page top: ''====== Main title ======''
    * Section: ''===== Section 1 =====''
    * Etc...

  * When a page has many sections, you can start with an **Overview** section describing the various sections
===== Screenshots =====
  * Screenshots are difficult to maintain as the application evolves and should be kept minimal
  * Do not use screenshot to emphasize trivial description or procedure such as:
    * Navigation (clicking buttons, links, etc...)
    * Simple formulars
  * One section should not contain more than 1 or 2 screenshots
  * Use screenshot only when
    * it is meaningfull
    * When a dialog or a screen has multiple interations difficult to describe
  * Avoid too large screenshots, should be limited to 1000px
    * Add ''?width=1000'' to the screenshot link

===== Style and Grammar =====
  * Documentation must be written in **clear english**
  * Use **online corrector** or AI such as chatGTP to correct or reformulate your sections
  * Avoid too long wiki page, prefere creating dedicated page when a section is too long to describe
  * You can use **bold** to emphasize some important notion or keywords, example:
    * **Warning**: Always carfuly check permissions of your dashboards
    * Only **admin** users can delete systems
  * Do not **over use bold**, you will confuse the reader and lose the point.
  * Use ''Monospaced Text'' for commands or menu/button labels, example:
    * Press ''Generate'' before using the role
    * Run ''systemctl start service'' to run the application
  * Do not **over explain** trivial actions. Readers are supposed to be users with technical background. Example of unecessary text:
    * Press the ''Save'' button to save your dashboard.
    * Type your name in the ''Name'' field

===== Links =====
  * Avoid creating too long pages by using links toward a new page to describe specific sections
  * This also allows to jump to a specific page from the Redpeaks application.
  * Example with dashboard widget: 
    * Each widget will have a help link opening the dedicated widget page, not the overall dashboard documentation.
  * Careful when creating links (edit the page to see the markup):
    * ''[[section|My section]]'' -> creates a page at the same folder level than **current** page 
    * ''[[.:documentation:section|My section]]'' -> creates a page within a **subfolder** of current page