A lot of useful information for the :term:`operator` is naturally present when defining our variables. I'm thinking of its type, the constraints applied, its default value, the mode level, etc.
But it is still necessary, as an :term:`integrator`, to guide the :term:`operator`.
Describe the variable
---------------------
Describing the variable you create is not mandatory but it is highly recommended.
Even a very well-chosen variable name does not replace a description.
..glossary::
description
A description allows you to describe the expected value(s) of a variable concisely and clearly.
It is designed to be clear precise and short.
The description is used in different places in Rougail.
Examples include:
- warning/error message
- different output
Additional help to understand the variable
------------------------------------------
Help is a property that only concerns documentation.
..glossary::
help
A help helps to clarify any ambiguity about the variable’s purpose.
It can be long and detailed.
..seealso:: tutorial with a real world sample :doc:`help <../tutorial/examples>`
Give examples of possible value
-------------------------------
Often a good example is more effective than a long text.
Don't hesitate to guide the :term:`operator` with relevant examples.
Examples is a property that only concerns documentation.
..seealso:: tutorial with a real world sample :doc:`examples <../tutorial/examples>`
In a context of value presentation, :term:`tagging <tag>` can be very useful. The :term:`tags <tag>` allow you to display variable values without knowing the list of variable paths.
