Data documentation ================== Documentation is an integral part of the definition of structured data. In a sense, we talk about `structured data` and not `schema` in Rougail because the documentation is an integral part of the variable definition. More broadly, considering the use of a 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>` Specialize variables -------------------- In a context of value presentation, tags can be very useful. They allow you to display variable values without knowing the list of variable paths. .. glossary:: tag A tag is just a name. It add tags are a way to attach additional information or labels to variables.