Improve clarity in docs/readme (#2066)

* Improve instructions for docs contribution

* Fix link to docs/readme

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index f154d95a29f9948dda6feaa4f8d8a64ab68519cd..3814c3f5255891f2d585a2bc9cbe7d8ad6c6f843 100644 (file)
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -22,7 +22,7 @@ npm install
 npm run build
 ```
 
-To see documentation changes check [the documentation readme](docs/README.md).
+To see documentation changes check [the documentation readme](../docs/README.md).
 
 ### Bulma Sass styleguide
 

diff --git a/docs/README.md b/docs/README.md
index a8a872fc654c36f6f8c05237415860c39302f3d2..56e86a430c34495f0042a58f49fecf9b4870e6de 100644 (file)
--- a/docs/README.md
+++ b/docs/README.md
@@ -3,17 +3,25 @@
 The documentation HTML is produced with the Ruby-based `jekyll` tool.
 
 1. Make sure Ruby 2.x is installed.
-2. `gem install jekyll`
+2. `gem install jekyll` if `jekyll` is not already installed.
 
-> **Note**: If you are an ```Ubuntu user``` Make sure ruby2.x-dev is installed
+> **Note**: If you are an ```Ubuntu user```, make sure ruby2.x-dev is installed.
 
 ## Viewing the documentation locally
 
-Then to view the documentation in your local checkout:
+To view the documentation on your system locally:
+
+### Setup
+
+1. `cd` into `docs/` directory
+1. Copy the config file, `cp _config.yml _config.local.yml`
+1. Edit `_config.local.yml` and change the `url:` value to `http://localhost:4000`. This local config file will be ignored by git.
+
+### Run Jekyll
 
-1. Before you begin, cd into `docs/` directory, and `cp _config.yml _config.local.yml`. Then edit `_config.local.yml` and change the `url:` value to `http://localhost:4000`. This local config file will be ignored by git.
 1. In a separate shell session, `cd` to the `docs/` directory, and do:
 ```
 jekyll serve --incremental --config _config.local.yml
 ```
+
 This will start an HTTP server at `http://localhost:4000/` that serves the docs built in the `_site` directory; and anytime the docs are rebuilt by you, it will serve the docs site on the fly. In your main shell session where you develop, if you change anything in `docs/` the jekyll server will rebuild those on the fly. But if you change anything about the Bulma SASS or CSS, you need to do `npm run start-docs` to build the docs' CSS before you will see it in the browser. The process running `jekyll serve` will pick up the new CSS automatically.