70 lines
2.2 KiB
ReStructuredText
70 lines
2.2 KiB
ReStructuredText
|
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.
|