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 full 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 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 integrator, to guide the 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.

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.

help: A help helps to clarify any ambiguity about the variable’s purpose. It can be long and detailed.

Give examples of possible value

Often a good example is more effective than a long text.

Don’t hesitate to guide the operator with relevant examples.

Examples is a property that only concerns documentation.

Specialized variables

In a context of value presentation, tagging can be very useful. The tags allow you to display variable values without knowing the list of variable paths.

tag: A tag is just a name. Adding a tag is a way to attach additional information or label to variables.