diff --git a/README.md b/README.md
index 1f21194ed..cef0aac0b 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 This repo contains all documentation for fastlane. You can find the `.md` files inside the [docs](docs) folder.
 
-To preview the updated documentation locally, just clone the repo, modify the file, and run
+To preview the updated documentation locally, just clone the repo, modify the file, and run. Note that some of the files are in [generated](docs/generated) folder and are later copied with mkdocs prebuild hook.
 
 ```
 mkdocs serve
@@ -24,10 +24,17 @@ Once a PR is merged into master, the latest version will automatically be deploy
 brew install python3 # if you don't have pip already
 brew install pipenv
 pipenv --three
-pipenv shell
+# install dependencies from Pipfile.lock and run shell
 pipenv install
+pipenv shell
 ```
 
 ## Adding a Python dependency
 
 Likely, to add a [Markdown extension](https://pythonhosted.org/Markdown/extensions/), install it with `pipenv install <some extension>` after making sure the virtualenv is loaded (`pipenv shell`).
+
+## Troubleshooting local docs server
+
+Running local server with `mkdocs serve` takes several minutes. It looks like `mkdocs` needs several minutes to read `available-plugins.md`. It can be confirmed by running `mkdocs serve --verbose` as `mkdocs` is stuck at reading this file.
+
+To test changes on other pages than list of available plugins, its convenient to edit `docs/generated/available-plugins.md` and remove all its content and save file before running `mkdocs serve`.