.. _data_documentation:

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/document>`

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/document>`

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.
