README.md in reek-5.0.2 vs README.md in reek-5.1.0

@@ -405,10 +405,20 @@
 end
 ```
 
 This is an incredibly powerful feature and further explained under [Smell Suppresion](docs/Smell-Suppression.md).
 
+#### Debugging trouble with the configuration
+
+With Reeks dynamic mechanism of finding a configuration file you might run into a situation where you are not
+100% sure what configuration file Reek is using. E.g. you have a project specific configuration file in your
+project root and also another Reek configuration in your HOME directory that you use for all your other projects
+and for whatever reasons Reek seems to be using another configuration file than the one you assumed it would.
+
+In this case you can pass the flag `--show-configuration-path` to Reek which will cause Reek to output the path
+to the configuration file it is using.
+
 ### Generating a 'todo' list
 
 Integrating tools like Reek into an existing larger codebase can be daunting when you have to fix
 possibly hundreds or thousands of smell warnings first.
 Sure you could manually disable smell warnings like shown above but depending on the size of your
@@ -418,43 +428,44 @@
 
 ```Bash
 reek --todo lib/
 ```
 
-This will create the file '.todo.reek' in your current working directory.
+This will create the file '.reek.yml' in your current working directory.
 
 You can then use this as your configuration - since your working directory
 probably is your project root in most cases you don't have to tell Reek
-explicitly to use '.todo.reek' because Reek will automatically pick it up
+explicitly to use '.reek.yml' because Reek will automatically pick it up
 and use it as configuration file. See [Configuration Loading](#configuration-loading) above.
 
-If for whatever reasons you decide to put '.todo.reek' somewhere else where
+If for whatever reasons you decide to put '.reek.yml' somewhere else where
 Reek won't pick it up automatically you need to tell Reek explicitly to do so
 via:
 
 ```Bash
-reek -c whatever/.todo.reek lib/
+reek -c whatever/.reek.yml lib/
 ```
 
 It's important to understand that the number one use case of the `--todo` flag
 is to be run once at the beginning of the introduction of Reek to ease the transition.
-If you find yourself re-running Reek with the `--todo` flag in order to silence new warnings
+If you find yourself wanting to re-run Reek with the `--todo` flag in order to silence a lot of new warnings
 you're defeating the purpose of both the `--todo` flag and of Reek itself.
 
-As a consequence, running Reek with the `--todo` flag again will overwrite '.todo.reek' without
-asking (should not be a problem since this file is supposed to be versioned) and
-without taking **any** other configuration file you might have into account.
+As a consequence, running Reek with the `--todo` flag again will not overwrite an existing '.reek.yml'
+and instead abort execution. It also will not take **any** other configuration file you might have into account.
 
 This means that when you run
 
 ```Bash
 reek -c other_configuration.reek --todo lib/
 ```
 
-`other_configuration.reek` will simply be ignored (as outlined before, Reek
-is supposed to have one configuration file and one file only).
+`other_configuration.reek` will simply be ignored.
 
+Of course you can always just delete the existing .reek.yml file and then run Reek with the `--todo` flag
+but keep in mind that this is not the intended use case of this feature.
+
 ## Usage
 
 Besides the obvious
 
 ```Bash
@@ -490,20 +501,10 @@
 bundle exec rake
 ```
 
 This will run the tests (RSpec and Cucumber), RuboCop and Reek itself.
 
-You can also run:
-
-```
-bundle exec rake ci
-```
-
-This will run everything the default task runs and also
-[Ataru](https://github.com/CodePadawans/ataru). This is the task that we run on
-Travis as well and that determines if your pull request is green or red.
-
 Another useful Rake task is the `console` task. This will throw you right into an environment where you can play around with Reeks modules and classes:
 
 ```
 bundle exec rake console
 
@@ -518,18 +519,9 @@
 
 ```Ruby
 require 'pry'
 binding.pry
 ```
-
-If you do this, you need to also run the specs with `DEBUG=1` set, e.g.:
-
-```
-DEBUG=1 bundle exec rspec spec/your/file_spec.rb:23
-```
-
-This is necessary because normally all specs run with a timeout of 5 seconds,
-which isn't much if you're busy using Pry.
 
 Have a look at our [Developer API](docs/API.md) for more inspiration.
 
 From then on you should check out: