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):

My section -> creates a page at the same folder level than current page

My section -> creates a page within a subfolder of current page