Update Readme: Fix punctuation and reorganize and edit sections for b…

…etter clarity

README.md

@@ -11,7 +11,9 @@ Some available and ready-to-use devstack images are going to help you running th
 ## Documentation
 An extensive documentation on the architecture and the toolkit commands can be found in the repo's wiki page [here](https://github.com/appsembler/sultan/wiki).
 
-Appsembler Internal Doc [here](https://appsembler.atlassian.net/wiki/spaces/~869427582/pages/1556250675/Sultan+Appsembler).
+> **APPSEMBLER TEAM MEMBERS**
+>
+> Additional internal documentation on setup and development can be found [here](https://appsembler.atlassian.net/wiki/spaces/~869427582/pages/1556250675/Sultan+Appsembler).
 
 ## 1. Before you start
 - Make sure you have your SSH key added into our GCP Appsembler Devstack (appsembler-devstack-30) project. You can check that at GCP [Compute Metadata](https://console.cloud.google.com/compute/metadata/sshKeys?project=appsembler-devstack-30).
@@ -21,48 +23,56 @@ Appsembler Internal Doc [here](https://appsembler.atlassian.net/wiki/spaces/~869
 ## 2. Quick Start
 
 ### 2.1. Clone and configure
-If you're on Linux, follow the next steps to set up your Sultan devstack
+If you're on Linux, follow the next steps to set up your Sultan devstack:
 
 ```console
 $ git clone git@github.com:appsembler/sultan.git
 $ cd sultan
-$ sultan config init  # Make sure you're in the correct python environment, this will install the required package immediatly one you run it.
-## configs/.configs.username is created
+$ sultan config init  # Make sure you're in the correct python environment first as this will install the required package immediatly once you run it.
+## configs/.configs.$USER is created
 ```
 
-If you're on macOS, follow the steps to set up your Sultan devstack
+If you're on macOS, follow these steps to set up your Sultan devstack:
 
 ```console
 $ git clone git@github.com:appsembler/sultan.git
 $ cd sultan
-$ ./sultan config init
+$ ./sultan config init # Make sure you're in the correct python environment first as this will install the required package immediatly once you run it.
+## configs/.configs.$USER is created
 ```
+> **NOTE**
+>
+> For macOS users, check the [optional configurations](https://github.com/appsembler/sultan/edit/master/README.md#accessing-sultan-from-any-directory-on-your-machine) section to allow you to type `sultan` instead of `./sultan`. Otherwise every `sultan` command referenced in this readme here onwards needs to be typed as `./sultan` from your local sultan directory.
 
 > **NOTE**
 >
-> All the generated files will exist in `$SULTAN_HOME`, you can change the value of this from you configurations file.
+> All the generated files will exist in `$SULTAN_HOME`, you can change the value of this from your configurations file.
 
 
 ### 2.2. Required configurations
-The following configurations must be overridden in your recently-created config 
-file: 
+The following configurations must be overridden in your recently created config file:
 
-* `SSH_KEY`: The private key that has access to the GCP project where we will 
-create your instance
+* `SSH_KEY`: The path to your private key that has access to the GCP project where we will create your instance.
 * `PROJECT_ID`: The GCloud project ID.
-* `SERVICE_ACCOUNT_EMAIL`: A string that we will use to create a service account. 
-* `SERVICE_KEY_PATH`: Path to the service account key created in the steps above. 
+* `SERVICE_ACCOUNT_EMAIL`: A service account email with the required permissions.
+* `SERVICE_KEY_PATH`: Path to the downloaded service account key JSON file for the above service account.
 
-More about this later in [Working with configurations](#3-working-with-configurations)
-section.
+More details on these values in the [3. Working with configurations](#3-working-with-configurations)
+section. Once configured, come back to this step.
+
+> **NOTE**
+>
+> - Make sure you're editing the values in your `.configs.$USER` config file and not the `.configs` template file.
 
 ### 2.3. Create your first devstack
-Create an instance from a pre-packaged image
+Create an instance quickly from a pre-packaged image:
 
 ```console
 $ sultan instance setup --image devstack-juniper
 ```
 
+Further instructions from here onwards on setting up the devstack and development in the [4. Creating your first edX devstack instance](https://github.com/appsembler/sultan/edit/master/README.md#4-creating-your-first-edx-devstack-instance) and [5. Development](https://github.com/appsembler/sultan/edit/master/README.md#5-development) sections.
+
 ## 3. Working with configurations
 
 ### 3.1. Local environment set up
@@ -75,27 +85,23 @@ your devstack instance (official docs [here](https://cloud.google.com/iam/docs/c
 docs [here](https://cloud.google.com/iam/docs/granting-roles-to-service-accounts#granting_access_to_a_service_account_for_a_resource)). 
 1. Grant the service account `roles/compute.instanceAdmin` role (See also 
 the [list of roles](https://cloud.google.com/sdk/gcloud/reference/iam/roles/list)).
-1. Download the service account on your machine.
+1. Download the service account key to your machine (follow the official docs ([here](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)) to generate a key for your service account).
 
 ### 3.2. Getting sultan configurations ready
-1. After downloading the service account, edit the value of `SERVICE_KEY_PATH` 
-to match its location. (Follow the official docs ([here](https://cloud.google.com/iam/docs/creating-managing-service-account-keys)) 
-to generate a key for your service account).
-1. Edit (uncomment, set) the following values in your configs file
+1. After downloading the service account key, edit the value of `SERVICE_KEY_PATH` to match its location on your machine.
+1. Change the following values in your `.configs.$USER` file:
 
 ```shell
 ## File configs/.configs.$USER
-SSH_KEY="$(HOME)/.ssh/id_rsa"
+SSH_KEY="$(HOME)/.ssh/<your-private-ssh-key>"
 PROJECT_ID=<gcp-project-id>
 SERVICE_ACCOUNT_EMAIL=email@<gcp-project-id>.iam.gserviceaccount.com
-SERVICE_KEY_PATH=/path/to/service/key.json
+SERVICE_KEY_PATH=/path/to/service/account/key.json
 ```
 
-> **NOTE**
+> **APPSEMBLER TEAM MEMBERS**
 >
-> - This example has my values
-> - You should change the value `SERVICE_KEY_PATH` if you decided to copy and 
-> paste the configurations above.
+> Refer to the internal documentation [here](https://appsembler.atlassian.net/wiki/spaces/~869427582/pages/1556250675/Sultan+Appsembler) for these values.
 
 ### 3.3. Optional configurations
 
@@ -105,31 +111,26 @@ for fault-tolerant workloads. They offer the same machine types and options as
 regular compute instances and last for up to 24 hours, and can reduce your 
 Compute Engine costs by up to 80%!
 
-Sultan allows you to setup a preemptible machine, you can do that by setting
-the configuration variable `PREEMPTIBLE` to `true`. Just something to note 
-here, preemptible machines are not suitable for long provisioning work, we only 
-recommend using them with `sultan instance setup --image` command. If you 
-noticed a freeze in your machine's shell, it means that your machine got 
-interrupted, and you might have to restart the session again.
+Sultan allows you to setup a preemptible machine. You can do that by setting the configuration variable `PREEMPTIBLE` to `true`. Just something to note here: preemptible machines are not suitable for long provisioning work — we only recommend using them with `sultan instance setup --image` command. If you noticed a freeze in your machine's shell, it means that your machine got interrupted, and you might have to restart the session again.
 
 #### Machine lifespan
 When you create a sultan instance, the instance will be configured to run for 
 a specific amount of time configured in `ALIVE_TIME` in the configurations 
-file. We sat the default lifespan to 6 hours, when your machine powers off
-you can start it again using 
+file. We set the default lifespan to 6 hours, but when your machine powers off
+you can start it again using:
 ```
 $ sultan instance start
 ```
 
-To stop the machine manually before the timeout use
+To stop the machine manually before the timeout use:
 ```shell
 $ sultan instance stop
 ```
 
 #### Exposed ports
 For security reasons, Sultan firewall will restrict access to the ports in
 `EXPOSED_PORTS` in your .configs file. Here's the full list of the ports you
-might want to enable.
+might want to enable:
 
 > **NOTE**
 >
@@ -158,13 +159,15 @@ might want to enable.
 
 #### Accessing `sultan` from any directory on your machine 
 If you want to access `sultan` command line from any directory, add this repo 
-dir to your `PATH`
+dir to your `PATH`:
 ```console
 $ export PATH=$PATH:$(pwd)  # pwd should translate to /path/to/projects/sultan
 ```
 
+The above command will only add this repo dir to your `PATH` variable for that particular session. If you want to permanently add it, modify your `~/.bashrc` or `~/.zshrc` file by adding the line with the actual output of `pwd`: `export PATH="$PATH:/path/to/your/sultan/dir"`.
+
 #### Enabling auto completion 
-To enable auto completion
+To enable auto completion:
 ```console
 $ source extras/sultan-completion.bash  # For bash shell
 $ source extras/sultan-completion.zsh   # For zsh shell
@@ -180,7 +183,7 @@ possible. You can check it here: http://www.gcping.com/ Following example will
 be how I’ve set it up (the ZONE value) in Europe.
 
 For minimum latency. You can set `ZONE` value to match the nearest GCP zone to 
-you.
+you:
 ```shell
 ## File configs/.configs.$USER
 ZONE=europe-west3-c
@@ -199,7 +202,7 @@ DEBUG=false
 We created a custom env variable for the devstack run command. EdX 
 uses `dev.up` to get the devstack services running. However, in Appsembler we
 use some other services that requires extra environment variables such as 
-`HOST`. So simply what we can do here is
+`HOST`. So simply what we can do here is:
 ```
 ## File configs/.configs.$USER
 DEVSTACK_RUN_COMMAND="HOST=tahoe dev.up"
@@ -213,27 +216,25 @@ DEVSTACK_RUN_COMMAND="HOST=tahoe dev.up"
 ## 4. Creating your first edX devstack instance
 
 ### 4.1. Setting up the devstack
-Simple as running
+Simple as running:
 ```console
 $ IMAGE_NAME=devstack-juniper  # Or any other devstack image name
 $ sultan instance setup --image $IMAGE_NAME
 ```
 
 The previous command will spin an instance for you from an already created 
-image. However, if you prefer to run the full setup from scratch just don't
-supply an `image` argument. 
+image, so it's the quickest way to get started. However, if you prefer to run the full setup from scratch, just don't
+supply an `image` argument:
 
 ```console
 $ sultan instance setup
 ```
 
-Make yourself some coffee. Go for a jog. Recreate the Sistine Chapel painting.
-Actually, go and built the chapel first. Then do the painting. You’ll have 
-time. A full setup takes quite long. But, once it’s finished…
+Keep in mind that this will take <ins>several</ins> hours. Make yourself some coffee. Go for a jog. Recreate the Sistine Chapel painting. Actually, go and build the chapel first. Then do the painting. You’ll have time. A full setup takes quite long, but once it’s finished…
 
 
 ### 4.2. Bring up devstack up
-To run the devstack
+To run the devstack:
 ```console
 $ sultan devstack up
 ```
@@ -291,7 +292,7 @@ In order to do so, simply run:
 $ sultan image create
 ```
 
-You can also specify a name for your image using
+You can also specify a name for your image using:
 ```console
 $ sultan image create --name my-lovely-image
 ```
@@ -311,12 +312,12 @@ $ sultan instance start
 $ sultan devstack up
 ```
 
-Stopping? No problem
+Stopping? No problem:
 ```console
 $ sultan instance stop  ## Will stop your devstack firts, then the instance.
 ```
 
-Want to get rid of it?
+Want to get rid of it? Type this:
 ```console
 $ sultan instance delete
 ```
@@ -430,13 +431,13 @@ again `sultan devstack mount`. Works like a charm.
 
 ## 6. Configurations variables
 We create a specific ignored .configs file for you when you ran `sultan config init`, 
-to debug the interpreted values of your configs that sultan reads you can run
+to debug the interpreted values of your configs that sultan reads you can run:
 ```console
 $ sultan config debug
 ```
 
 ## 7. Tool help
-To check sultan commands' documentation run
+To check sultan commands' documentation run:
 ```console
 $ sultan -h
 $ sultan --help
@@ -463,7 +464,7 @@ If you couldn't identify the cause of the problem, please submit an issue on htt
 #### LMS pages show TypeError exception
 ##### Problem
 The exception below shows up on every (or most) lms pages 
-a [full example log is available in this gist](https://gist.github.com/grozdanowski/d6237342d3b693e19dfff4c43b0b1585).
+a [full example log is available in this gist](https://gist.github.com/grozdanowski/d6237342d3b693e19dfff4c43b0b1585):
 ```
 TypeError: _clone() takes exactly 1 argument (3 given)
 ```