Improve configurability documentation

Spawned from https://github.com/bazelbuild/bazel/issues/5574#issuecomment-667299335.

Specific ideas:

- [ ] Update [configurable build attributes](https://docs.bazel.build/versions/3.4.0/configurable-attributes.html#custom-keys) intro doc to reflect Starlark flag support
- [ ] Minimize uses of `--define` in doc examples
- [ ] Platforms example: why is everything [specified twice](https://docs.bazel.build/versions/master/configurable-attributes.html#platforms)? (from https://github.com/bazelbuild/bazel/issues/5574#issuecomment-667670328)
- [ ] Make the difference between `constraint_setting`, `config_setting`, `build_setting`, `platform`, etc. clearer
- [ ] State current reality and best practices vs. "this will be possible in the future"
- [ ] Clearer, more actionable error messaging

Start with the linked configurable build attributes introduction and platforms example documentation, then review the listed ideas against current Starlark flag and platform behavior. Done means updating the explanations and examples, clarifying the terminology and current best practices, and addressing the requested error-message guidance.

Written by the indexing model from the issue text.