Clarify --compilation_mode usage

### Description of the problem / feature request:

`compilation_mode` is great, but few people know, understand and use it.

For rule developers, it's common to have a rule that produces different outputs based on debugging/optimization settings. So we ended with having attributes like `debug`, `compress` etc on the rules, which is annoying and also less optimal to use for various reasons.

Throughout the entire rule design [totorial](https://docs.bazel.build/versions/master/skylark/rules.html), `configuration_mode` is not mentioned. Without knowing such a configuration exists, people find their own way to solve an already solved problem.

Also per the [user manual](https://docs.bazel.build/versions/master/user-manual.html#flag--compilation_mode):

> This option takes an argument of `fastbuild`, `dbg` or `opt`, and affects various C/C++ code-generation options, such as the level of optimization and the completeness of debug tables. Bazel uses a different output directory for each different compilation mode, so you can switch between modes without needing to do a full rebuild _every time_.

It gives the impression that `compilation_mode` only works for C/C++ builds, but it's something that affects all rules that support it. Having those misleading statements are not promoting the usage of this feature.

Start with the linked Skylark rules tutorial and the user manual's --compilation_mode section. Clarify the configuration's relevance to rule developers and correct the wording that suggests it only affects C/C++ builds; done means both linked documentation areas explain its broader use consistently.

Written by the indexing model from the issue text.