Improvement to docs: add more examples
Quite often I find myself wondering how an actual example would look like, and the only way to find out is trying out variations of what one think is hinted at in the docs. It would save a lot of people time if the docs included some more example strings. Example: the path strings used as rules in various build features and vcs configurations ("+|-:").
Take this doc page on Xml report processing. It says "specify monitoring rules in the form of +|-:path". OK ... That pipe character ... is that a logical "OR" operator or should it be part of the string? I.e. does it mean one can either write "+: path" or "-: path"?
The next line doesn't really help: "Paths without the +|: prefix are treated as including". Oh, so the pipe character should be included in the inclusive rules? So does it mean the lines should really be "+|: my/path/that/is/included"?
And so on ...
Slow feedback loops kills productivity! Just provide some examples :)
Please sign in to leave a comment.
Hi Carl-Erik,
thanks for your feedback. I've forwarded it to the team and we'll be discussing how to improve on this, as there is a pretty large amount of this instances in the docs, so it would make sense to make a more systematic approach rather than fix them manually one by one.
This said, for all such examples, we tend to use ant-like rules, as they come from a long time ago, which means using "+:<path>" or "-:<path>". I guess it will be fine for you now, but in case somebody stumbles upon this looking for the answer.