Improve clarity in docs/readme (#2066)

* Improve instructions for docs contribution * Fix link to docs/readme
jgthms · Oct 7, 2018 · 333bcf8 · 333bcf8
1 parent 0e15807
commit 333bcf8
Show file tree

Hide file tree

Showing 2 changed files with 13 additions and 5 deletions.
diff --git 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
@@ -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.