Tip: Include Context And Propose Solutions In Your Error Messages

A Puppet run has failed with an error message like this:

"No matching selector for 'prod' at some_puppet_file.pp:31"

If you know puppet well enough, you will immediatelly know what is wrong and how to fix it. But what if you don't know what a 'selector' is? Interpreting error messages is often hard without deep knowledge of the software. Be nice to the users / fellow programmers, do not expect they know everything, and include helpful context and preferably also suggest some possible solutions. If the message read instead:

"No matching selector for 'prod' at some_puppet_file.pp:31; the available selectors are 'production', 'test', 'staging'; have you forgotten to add 'prod' or default?"

wouldn't it be much more clear and helpful?