need for some clarifications and guidance

[nmayle]

Generally, it would be nice to see some guidance published to clarify some of the common mistakes that are being made in the files. While the syntax is specified and can be checked there are a number of semantic issues that seem to be fairly common and may be due to how people are interpreting the documentation.

Discussions in the GitHub forum are great, but I don't know they everyone creating a file has the time to read through the whole set of discussions and to decide which of the answers is the definitive answer.

Do others see the value in this?