Make a few edits to the new doc README

README.md

@@ -47,6 +47,8 @@ Online documentation is available at [seaborn.pydata.org](https://seaborn.pydata
 
 The docs include a [tutorial](https://seaborn.pydata.org/tutorial.html), [example gallery](https://seaborn.pydata.org/examples/index.html), [API reference](https://seaborn.pydata.org/api.html), and other useful information.
 
+To build the documentation locally, please refer to [`doc/README.md`](doc/README.md).
+
 
 Dependencies
 ------------
@@ -73,11 +75,12 @@ Testing
 
 Testing seaborn requires installing additional packages listed in `ci/utils.txt`.
 
-To test the code, run `make test` in the source directory. This will exercise both the unit tests and docstring examples (using [pytest](https://docs.pytest.org/)).
+To test the code, run `make test` in the source directory. This will exercise both the unit tests and docstring examples (using [pytest](https://docs.pytest.org/)) and generate a coverate report.
+
+The doctests require a network connection (unless all example datasets are cached), but the unit tests can be run offline with `make unittests`.
 
-The doctests require a network connection (unless all example datasets are cached), but the unit tests can be run offline with `make unittests`. Run `make coverage` to generate a test coverage report and `make lint` to check code style consistency.
 
-To build seaborn's documentation, please refer to [how to build the docs?](doc/README.md).
+Code style is enforced with `flake8` using the settings in the [`setup.cfg`](./setup.cfg) file. Run `make lint` to check.
 
 Development
 -----------

doc/README.md

@@ -1,10 +1,10 @@
-How to build the docs?
-======================
+Building the seaborn docs
+=========================
 
-Building the docs requires installing the dependencies listed in `requirements.txt`.
+Building the docs requires additional dependencies listed in [`./requirements.txt`](./requirements.txt).
 
-The building process involves conversion of Jupyter notebooks to `rst` files. To facilitate this you need to set `NB_KERNEL` environment variable to the desired python kernel (e.g. `export NB_KERNEL="python3"`). To get a list of python kernels available, run `jupyter kernelspec list`.
+The build process involves conversion of Jupyter notebooks to `rst` files. To facilitate this, you may need to set `NB_KERNEL` environment variable to the name of a kernel on your machine (e.g. `export NB_KERNEL="python3"`). To get a list of available Python kernels, run `jupyter kernelspec list`.
 
-After you're set, from the `doc` directory run `make notebooks html` to convert all notebooks, build all gallery examples and the documentation iteslf. The designated output folder is `_build/html`. 
+After you're set up, run `make notebooks html` from the `doc` directory to convert all notebooks, generate all gallery examples, and build the documentation itself. The site will live in `_build/html`. 
 
-Run `make clean` to delete a built documentation.
+Run `make clean` to delete the built site and all intermediate files. Run `make -C docstrings clean` or `make -C tutorial clean` to remove intermediate files for the API or tutorial components.