Merge pull request #203 from waldyrious/patch-1

Various improvements to the README

Author: lullis

README.md

@@ -1,6 +1,6 @@
 # quickstatements3
 
-Repository for the development of a new version of QuickStatements
+Repository for the development of a version 3 of the [QuickStatements](https://www.wikidata.org/wiki/Help:QuickStatements) tool for making bulk edits to [Wikidata](https://www.wikidata.org).
 
 ## Local development HOW TO
 
@@ -16,7 +16,9 @@ To build the development container
 > make build
 ```
 
-Make sure that you have an env file inside the local etc/ dir. This file contains all the **ENVIRONMENT VARIABLES** used by the system and must never be added to your git repo.
+
+Make sure that you have an env file inside the local etc/ dir.
+This file contains all the **ENVIRONMENT VARIABLES** used by the system and must never be added to your git repo.
 
 To generate a good secret key you can run with python 3.6+
 
@@ -30,6 +32,7 @@ To start all services (database, web server, run a shell inside the container)
 > make run
 ```
 
+
 If everything is correct, **Quickstatements** will be available at http://localhost:8000/
 
 If you are running this for the first time, you have to create a superuser for the Django admin. You can access the container with `make shell`. From there:
@@ -42,17 +45,19 @@ will run an interactive command which will ask you for your username, password,
 
 ## Wikibase server
 
-QuickStatements 3.0 uses the Wikibase REST API to interact with a Wikibase server. To define which server it is pointing to, define the `BASE_REST_URL` environment variable, pointing to the `rest.php` endpoint, as in `BASE_REST_URL=https://test.wikidata.org/w/rest.php`.
+QuickStatements 3.0 uses the Wikibase REST API to interact with a Wikibase server.
+To define which server it is pointing to, define the `BASE_REST_URL` environment variable, pointing to the `rest.php` endpoint.
+For example: `BASE_REST_URL=https://test.wikidata.org/w/rest.php`.
 
-It uses the Wikibase REST API provided in `/wikibase/v1` and the profile endpoint for the Oauth2 API, provided in `/oauth2` to check autoconfirmation status and authorize users.
+QuickStatements 3.0 uses the Wikibase REST API provided in `/wikibase/v1` and the profile endpoint for the Oauth2 API, provided in `/oauth2` to check autoconfirmation status and authorize users.
 
 Currently it's only possible to point at one Wikibase instance.
 
 ## OAuth
 
 This application uses OAuth2 with the Mediawiki provider.
 
-The grants we probably need are
+The grants we probably need are:
 
 * Perform high volume activity
   * High-volume (bot) access
@@ -69,25 +74,27 @@ After registering a consumer in
 
 This application is listening on `/auth/callback/`, so, when registering, define the callback endpoint as `https://yourdomain.com/auth/callback/`.
 
-After receveing the consumer id and secret, setup `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` environment variables.
+After receveing the consumer id and secret, set up the `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` environment variables.
 
 ### Developer access
 
-If you want to login with a developer access token, you need to register for yourself an owner-only consumer application for OAuth2. Follow the form and be sure to tick "This consumer is for use only by <YOUR USERNAME>".
+If you want to login with a developer access token, you need to register for yourself an owner-only consumer application for OAuth2.
+Follow the form and be sure to tick "This consumer is for use only by <YOUR USERNAME>".
 
 ### Integration tests
 
 To run Integration tests on https://test.wikidata.org, you'll need a developer access token (owner-only) to edit on `test.wikidata.org`.
 
-After obtaining it, define the environment variable `INTEGRATION_TEST_AUTH_TOKEN` in `etc/env` file as your developer access token. Then, run the tests with `make integration`.
+After obtaining it, define the environment variable `INTEGRATION_TEST_AUTH_TOKEN` in `etc/env` file as your developer access token.
+Then, run the tests with `make integration`.
 
 Alternatively, define that environment varibale inside the container shell and run the tests directly with `python3 manage.py test integration`.
 
 ## Toolforge deployment
 
-* Login and enter into the tool user
+* Log in and enter into the tool user
 * Clone the repository at `~/www/python/`
-* Update `uwsgi.ini` with the toolname. In this case, its `qs-dev`
+* Update `uwsgi.ini` with the tool name (in this case, it's `qs-dev`)
 * Create the environment variables file at `~/www/python/src/.env` with `install -m 600 /dev/null ~/www/python/src/.env` so that only your user can read it.
 * Run `deploy.sh`
 * Logs are at `~/uwsgi.log`