fix language

CONTRIBUTING.md

@@ -1,33 +1,29 @@
-**How to submit issue?**
-------------------------
-First, please see [contribution-guide.org](http://www.contribution-guide.org/) for steps we expect from contributors before submitting an issue or bug report. Be as concrete as possible, include relevant logs, package versions etc.
+# How to submit an issue?
+
+First, please see [contribution-guide.org](http://www.contribution-guide.org/) for the steps we expect from contributors before submitting an issue or bug report. Be as concrete as possible, include relevant logs, package versions etc.
 
 Also, please check the [Gensim FAQ](https://github.com/RaRe-Technologies/gensim/wiki/Recipes-&-FAQ) page before posting.
 
 **The proper place for open-ended questions is the [gensim mailing list](https://groups.google.com/forum/#!forum/gensim).** Github is not the right place for research discussions or feature requests.
 
-**How to add new feature / create PR / etc?**
----------------------
+# How to add a new feature or create a pull request?
 
-1. <a href="https://github.com/RaRe-Technologies/gensim/fork">Fork gensim repository</a>
+1. <a href="https://github.com/RaRe-Technologies/gensim/fork">Fork the Gensim repository</a>
 2. Clone your fork: `git clone https://github.com/<USERNAME>/gensim.git`
-3. Create new branch based on develop: `git checkout -b my-feature develop`
-4. Make all needed changes
-4. Check that all OK in your branch (in needed):
-   - Check PEP8: `tox -e flake8`
-   - Build documentation (work only for MacOS/Linux): `tox -e docs`
-   - Run base tests: `tox -e py{version}-{os}`, for example `tox -e py27-linux` or `tox -e py36-win` where
-      - `{version}` from `27`, `35`, `36` and 
-      - `{os}` from `win`, `linux`
-
-5. Add files, commit and push: `git add ... ; git commit -m "my commit message"; git push origin my-feature`
-6. Create PR on github. Please add clear description for PR and add all needed information to first message, for example:
-   - Number of issue that you fixed, like `#123`
-   - Motivation (why and how)
-   - Any useful related information
-   - ...
-
+3. Create a new branch based on `develop`: `git checkout -b my-feature develop`
+4. Implement your changes
+5. Check that everything's OK in your branch:
+   - Check it for PEP8: `tox -e flake8`
+   - Build its documentation (works only for MacOS/Linux): `tox -e docs`
+   - Run unit tests: `tox -e py{version}-{os}`, for example `tox -e py27-linux` or `tox -e py36-win` where
+      - `{version}` is one of `27`, `35`, `36` and
+      - `{os}` is either `win` or `linux`
+6. Add files, commit and push: `git add ... ; git commit -m "my commit message"; git push origin my-feature`
+7. [Create a PR](https://help.github.com/articles/creating-a-pull-request/) on Github. Write a **clear description** for your PR, including all the context and relevant information, such as:
+   - The number of the issue that you fixed, e.g. `Fixes #123`
+   - Motivation (why did you create this PR, what functionality does it seek to improve, what was the problem + an overview of how you fixed it, whom does it help and how should people use it…)
+   - Any other useful information (links to other related Github or mailing list issues and discussions, benchmark graphs, academic papers…)
 
-P/S: for developers: see our [Developer Page](https://github.com/piskvorky/gensim/wiki/Developer-page#code-style) for details on code style, testing and similar.
+P.S. for developers: see our [Developer Page](https://github.com/piskvorky/gensim/wiki/Developer-page#code-style) for details on the Gensim code style, CI, testing and similar.
 
-Thanks!
+Thanks and let's improve the open source world together!