Problem

Recently we added the concept of different documents inside the same YAML file. This concept gives us more flexibility since we now can have different repositories for different sections of the same YAML file.

Although this is a great idea, the docs are not clear about it and a user needs to read all of it to be able to understand that different sections are needed in the same YAML file depending on which properties/features he is trying to configure.

Suggested Solution

In the YAML reference docs, create one section for each document type.
Different sections could have different colors or at least a definition of each document that property fits in.