Make the docs clearer for new contributors

* Add an easy-to-see note at the top of `CONTRIBUTING.md` that points
  new contributors to the Basics docs
* Add a note about compiler errors as a result of internals changes
  that break Clippy

2 files changed, 8 insertions, 2 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index dfc5cc077c3..5f7b1e85ee9 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -28,11 +28,14 @@ All contributors are expected to follow the [Rust Code of Conduct].
 
 ## Getting started
 
-High level approach:
+**Note: If this is your first time contributing to Clippy, you should
+first read the [Basics docs](doc/basics.md).**
+
+### High level approach
 
 1. Find something to fix/improve
 2. Change code (likely some file in `clippy_lints/src/`)
-3. Follow the instructions in the [Basics docs](doc/basics.md) such as running the `setup-toolchain.sh` script
+3. Follow the instructions in the [Basics docs](doc/basics.md) to get set up
 4. Run `cargo test` in the root directory and wiggle code until it passes
 5. Open a PR (also can be done after 2. if you run into problems)
 
diff --git a/doc/basics.md b/doc/basics.md
index 5c07d9b98a5..c81e7f6e069 100644
--- a/doc/basics.md
+++ b/doc/basics.md
@@ -53,6 +53,9 @@ rustup-toolchain-install-master -f -n master -c rustc-dev -c llvm-tools
 rustup override set master
 ```
 
+_Note:_ Sometimes you may get compiler errors when building Clippy, even if you
+didn't change anything. Normally those will be fixed by a maintainer in a few hours. 
+
 ## Building and Testing
 
 Once the `master` toolchain is installed, you can build and test Clippy like