Clarifies the order of steps for documentation changes (#136)

* Documentation: Re-arranges order of items

* Readme: Fixes minor typo

* Documentation: Fixes minor grammatical things

README.md

@@ -28,7 +28,7 @@ It will start a server at [localhost:3000](http://localhost:3000). You will need
 
 ### Adding a page
 
- - Create new page in `docs/`
- - Add new doc to `website/sidebars.json`
+- Create new page in `docs/`
+- Add new doc to `website/sidebars.json`
 
 You will need to restart the server when creating a new file or make changes to `sidebars.json`. If you're updating a document, you will only need to refresh your browser to get the latest changes.

docs/documentation_index.md

@@ -15,7 +15,8 @@ For larger changes, we suggest that you clone the website repository. This way,
 To test your changes locally, you need to install **Ruby** and its dependencies (gems):
 
 - [Install Ruby](https://www.ruby-lang.org/en/documentation/installation/) if you don't have it already. Ruby version 2.3.0 or higher is required.
-- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler`
+- Install `bundler`, a dependency manager for Ruby: `$ gem install bundler` (You might have to run this command as `sudo`).
+- Fork the home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.io).
 - In your home-assistant.io root directory, run `$ bundle` to install the gems you need.
 
 Shortcut for Fedora: `$ sudo dnf -y install gcc-c++ ruby ruby-devel rubygem-bundler rubygem-json && bundle`
@@ -23,19 +24,18 @@ Shortcut for Debian/Ubuntu: `$ sudo apt-get install ruby ruby-dev ruby-bundler r
 
 Then you can work on the documentation:
 
-- Fork home-assistant.io [git repository](https://github.com/home-assistant/home-assistant.io).
-- Create/edit/update a page. The components/platforms documentation is located in `source/_components/`. `source/_docs/` contains the Home Assistant documentation itself. 
-- Test your changes to home-assistant.io locally: run `bundle exec rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000)
+- Run `bundle exec rake generate` to generate the every first preview. This will take a couple of minutes.
+- Create/edit/update a page. The components/platforms documentation is located in `source/_components/`. `source/_docs/` contains the Home Assistant documentation itself.
+- Test your changes to home-assistant.io locally: run `bundle exec rake preview` and navigate to [http://127.0.0.1:4000](http://127.0.0.1:4000). While this command is working, any changes to a file are automatically detected and will update the affected pages. You will have to manually reload them in the browser though.
 - Create a Pull Request (PR) against the **next** branch of home-assistant.io if your documentation is a new feature, platform, or component.
 - Create a Pull Request (PR) against the **current** branch of home-assistant.io if you fix stuff, create Cookbook entries, or expand existing documentation.
 
-It could be necessary that you run `bundle exec rake generate` prior to `bundle exec rake preview` for the very first preview.
-
-Site generated by `bundle exec rake` is only available locally. If you are developing on a headless machine, use port forwarding:
+The site generated by `bundle exec rake` is only available locally. If you are developing on a headless machine, use port forwarding:
 
 ```bash
 $ ssh -L 4000:localhost:4000 user_on_headless_machine@ip_of_headless_machine
 ```
+
 ## Speeding up site generation
 
 Every release we post long changelogs to the website. This slows down generation of the website significantly! We include some tools to temporarily exclude components and blog posts that you're not working on out of the way.