Documentation practices

Describes documentation practices to create clear and consistent documentation

• 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

• 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 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

• 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

• 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):
  • My section → creates a page at the same folder level than current page
  • My section → creates a page within a subfolder of current page