Clean up some of the documentation

docs/contributing_docs.md

@@ -1,4 +1,4 @@
-If you would like to improve the existing docs/ add new ideas in docs, you can do so by using mkdocs. Howdoi uses mkdocs to host its documentation. Steps to contribute to docs:
+If you would like to improve the existing documentation, you can do so by using `mkdocs`. Howdoi uses mkdocs to render its documentation. Steps to contribute to docs:
 
 - Every step from [Contributing to howdoi](http://gleitz.github.io/howdoi/contributing_to_howdoi/) remains the same with additional requirements of installing and building mkdocs.
 - First, install mkdocs by running the following command:

docs/contributing_to_howdoi.md

@@ -1,11 +1,11 @@
 As beginners, navigating the codebase and finding your way out of the documentation can become difficult. This page will help you understand everything about contributing to howdoi and the best practices in open source as well.
 You can either contribute code to Howdoi (explained on this page) or contribute documentation (explained on next page)
 
-#### 1- Setting up the development environment
+#### Setting up the development environment
 
 Follow the page [Setting up the development environment](http://gleitz.github.io/howdoi/development_env/) for setting up the development environment for Howdoi.
 
-#### 2 - Finding your first issue
+#### Finding your first issue
 
 - Go to issues in the [howdoi repo](https://github.com/gleitz/howdoi).
 - Find the issues which you might be interested to work on. Or, you can also come up with your own ideas of improving howdoi.
@@ -14,7 +14,7 @@ Follow the page [Setting up the development environment](http://gleitz.github.io
 - After receiving confirmation, start working on the issue and whenever and wherever help is needed, comment on the issue itself describing your query in detail.
 - A good guide on how to collaborate efficiently can be found [here](https://lab.github.com/githubtraining/introduction-to-github){:target="\_blank"}.
 
-#### 3 - Making a Pull request (PR)
+#### Making a Pull request (PR)
 
 - After you have worked on the issue and fixed it, we need to merge it from your forked repository into the howdoi repository. This is done by making a PR.
 - You can search
@@ -26,7 +26,7 @@ Follow the page [Setting up the development environment](http://gleitz.github.io
 
 - Once your commit passes all the tests, make a PR and wait for it to be reviewed and merged.
 
-#### 4 - Asking for help
+#### Asking for help
 
 At times, help is needed while solving the issue. We recommend the following step for asking for help when you get stuck:
 

docs/development_env.md

@@ -1,4 +1,4 @@
-- Clone the Howdoi repository:
+- Clone the howdoi repository:
 
   ```
   $ git clone https://github.com/gleitz/howdoi.git
@@ -6,28 +6,26 @@
 
 - To see how to set up the development for Windows, see [here](http://gleitz.github.io/howdoi/windows-contributing/).
 
-- Setup and activate a virtual environment
+- Set up and activate a virtual environment:
 
   ```
   $ python3 -m venv .venv
   $ source .venv/bin/activate
   ```
 
-- Install all the required packages
+- Install all the required packages:
 
   ```
   $ pip install -r requirements.txt
   ```
 
-- Run howdoi
-
 - Running from command line :
 
   ```
   $ python -m howdoi QUERY
   ```
 
-- Running from a python script : Go to your script in howdoi.howdoi() and pass your query in the argument.
+- From a Python script, you can call howdoi with `howdoi.howdoi` and pass your query in the argument.
 
 ```
 from howdoi import howdoi
@@ -35,7 +33,7 @@ query = "for loop python"
 output = howdoi.howdoi(query)
 ```
 
-Or , parse it yourself and then pass the arguments:
+Or, parse it yourself and then pass the arguments:
 
 ```
 from howdoi import howdoi
@@ -45,7 +43,7 @@ args = vars(parser.parse_args(query.split(' ')))
 output = howdoi.howdoi(args)
 ```
 
-#### Notes :
+#### Notes
 
-- **Parsing queries yourself is the older way to pass in queries and may be deprecated in the future. Prefer the first example.**
-- **If you try running python howdoi/howdoi.py (without -m) you might get ValueError: Attempted relative import in non-package.**
+- Parsing queries yourself is the older way to pass in queries and may be deprecated in the future. Please use the first example.
+- If you try running `python howdoi/howdoi.py` (without -m) you might get `ValueError: Attempted relative import in non-package`.

docs/index.md

@@ -1,5 +1,5 @@
 # howdoi
-Never have to open your browser to look for answers again.
+Never open your browser to look for answers again.
 
 Create tar archive:
 ```bash

docs/introduction.md

@@ -1,25 +1,25 @@
-Howdoi is an open source command line tool which gives answers to your questions in the command line itself. Howdoi can be used by anyone and everyone who finds themselves Googling for answers to their basic programming questions.
+Howdoi is an open source command line tool that gives answers to your questions right on the command line. Howdoi can be used by anyone and everyone who finds themselves Googling for answers to their basic programming questions.
 
-Example -
+You wonder:
 
 ```
 howdoi print hello in python
 ```
 
-Answer -
+We answer:
 
 ```
 print(“hello”)
 ```
 
-### Installation :
+### Installation
 
-To install Howdoi, these two requirements must be fulfilled:
+You'll need:
 
-- Pip should be installed in your local system.
-- Python 3.5 or above installed since Python 2.7 support is discontinued.
+- `pip`
+- Python 3.5 or above. Python 2.7 support is discontinued.
 
-To install Howdoi, simply run :
+To install howdoi:
 
 `pip install howdoi`
 

docs/troubleshooting.md

@@ -15,4 +15,3 @@ sudo chmod -R go+w /Library/Python/2.7/site-packages/
 
 An official lxml for python 3.3+ for windows has not yet been released. You may get an error while installing.
 Try and install an [unofficial binary for lxml](http://www.lfd.uci.edu/~gohlke/pythonlibs/#lxml).
-```

docs/usage.md

@@ -1,61 +1,47 @@
-To begin with howdoi, after installing howdoi, enter the following command:
+Let's start at the beginning.
 
 ```
 $ howdoi howdoi
 ```
 
-This will provide with every information you need about working with howdoi and every command/argument that is present in howdoi. For further information about every flag and environment variables type :
+For further information about flags and environment variables:
 
 ```
 $ howdoi -h
 ```
 
-#### Howdoi flags/arguments.
+#### Howdoi Flags and Arguments
 
-Howdoi comes with a set of predefined flags/arguments which can be set by you as per your choice. You can just type `howdoi -h` in your command line to see each argument and what they do.
-
-**Syntax** : `howdoi [flag/argument] QUERY`
-
-The available arguments currently are listed below:
-
-**- h, --help** : To see the help message which has all the information about every command
-
-**-p POS, --pos POS** : To select answer in any specified position.
-
-**-n NUM, --num NUM** : Defines the number of answers to return. By default, set to 1.
-
-**-a, --all**: Shows the full text of an answer
-
-**-l, --link**: Displays only the link of the answer
-
-**-j** : Displays the answer in JSON format. Useful when you are building on top of howdoi.
-
-**-c, --color**: Prints colorized output
-
-**-x, --explain**: Explains why the outputted answer was shown to you
-
-**-C, --clear-cache**: Clears the cache
-
-**-j, --json** : Outputs the answer in raw JSON format
-
-**-v, --version**: Displays your current version of howdoi.
-
-**-e [ENGINE], --engine [ENGINE]** : Allows to choose the search engine for the query. Currently supported - google, bing, duckduckgo
-
-**--save, --stash** : Enables stashing feature for a howdoi answer
-
-**--view** : Displayed the stash
-
-**--remove** : Removes an entry in your stash
-
-**--empty** : Empties the stash completely
-
-#### Howdoi Environment variables
-
-Howdoi enables the users to put the environment variables of their choice, the currently supported environment variables are :
-
-- **HOWDOI_COLORIZE** : Colorizes the output by default.
-- **HOWDOI_SEARCH_ENGINE** : changes the default search engine for StackOverflow links. By default the search engine is google but other supported are : bing, duckduckgo.
-- **HOWDOI_URL** : Changes the source url for answers. By default set to : stackoverflow.com. Currently supported here.
-- **HOWDOI_DISABLE_CACHE** : Howdoi uses cache for faster access to previously searched questions. If this environment variable is set, the caching functionality will be set. The cache resides in ~/cache/howdoi/.
-- **HOWDOI_DISABLE_SSL** : Allows you to disable SSL.
+```
+usage: howdoi [-h] [-p POS] [-n NUM] [-a] [-l] [-c] [-x] [-C] [-j] [-v] [-e [ENGINE]] [--save] [--view] [--remove] [--empty] [QUERY ...]
+
+instant coding answers via the command line
+
+positional arguments:
+  QUERY                 the question to answer
+
+optional arguments:
+  -h, --help            show this help message and exit
+  -p POS, --pos POS     select answer in specified position (default: 1)
+  -n NUM, --num NUM     number of answers to return (default: 1)
+  -a, --all             display the full text of the answer
+  -l, --link            display only the answer link
+  -c, --color           enable colorized output
+  -x, --explain         explain how answer was chosen
+  -C, --clear-cache     clear the cache
+  -j, --json            return answers in raw json format
+  -v, --version         displays the current version of howdoi
+  -e [ENGINE], --engine [ENGINE]
+                        search engine for this query (google, bing, duckduckgo)
+  --save, --stash       stash a howdoi answer
+  --view                view your stash
+  --remove              remove an entry in your stash
+  --empty               empty your stash
+
+environment variable examples:
+  HOWDOI_COLORIZE=1
+  HOWDOI_DISABLE_CACHE=1
+  HOWDOI_DISABLE_SSL=1
+  HOWDOI_SEARCH_ENGINE=google
+  HOWDOI_URL=serverfault.com
+```

mkdocs.yml

@@ -20,7 +20,7 @@ nav:
   - Contributing: contributing_to_howdoi.md
   - Contributing documentation: contributing_docs.md
   - Extension development: extension_dev.md
-  - howdoi advanced usage: howdoi_advanced_usage.md
+  - Howdoi advanced usage: howdoi_advanced_usage.md
   - Troubleshooting: troubleshooting.md
   - Development for Windows: windows-contributing.md