69 lines
2.2 KiB
ReStructuredText
69 lines
2.2 KiB
ReStructuredText
Data documentation
|
||
==================
|
||
|
||
Documentation is an integral part of the definition of :term:`structured data`.
|
||
|
||
In a sense, we talk about :term:`structured data` and not `schema` in Rougail because the documentation is an full part of the variable definition.
|
||
|
||
More broadly, considering the use of a :term:`VaC` tool has the advantage of eliminating the need to manage documentation oneself.
|
||
|
||
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>`
|
||
|
||
Specialized variables
|
||
-----------------------
|
||
|
||
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.
|
||
|
||
.. glossary::
|
||
|
||
tag
|
||
|
||
A tag is just a name.
|
||
Adding a tag is a way to attach additional information or label to variables.
|