Update the contributing guide to offer some more advice

1 files changed, 58 insertions, 32 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 890fb8f0..ec9239c1 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,8 +1,10 @@
 # Contributing to ALE
 
 1. [Guidelines](#guidelines)
-2. [Creating Pull Requests](#pull-requests)
-3. [Creating Pull Requests](#compiling)
+2. [Creating Issues](#issues)
+3. [Creating Pull Requests](#pull-requests)
+ 1. [Adding a New Linter](#adding-a-new-linter)
+ 2. [Adding New Options](#adding-new-options)
 
 <a name="guidelines"></a>
 
@@ -10,21 +12,44 @@
 
 Have fun, and work on whatever floats your boat. Take It Easy :tm:.
 
-When writing code, follow the [Google Vimscript Style Guide](https://google.github.io/styleguide/vimscriptguide.xml), and
-run `vint -s` on your files to check for most of what the guide mentions and more. If you install this plugin and install
-[Vint](https://github.com/Kuniwak/vint), it will check your code while you type.
+When writing code, follow the [Google Vimscript Style
+Guide](https://google.github.io/styleguide/vimscriptguide.xml), and run `vint
+-s` on your files to check for most of what the guide mentions and more. If you
+install this plugin (ALE) and install [Vint](https://github.com/Kuniwak/vint), it
+will check your code while you type.
 
+<a name="issues"></a>
+
+# 2. Creating Issues
+
+Before creating any issues, please look through the current list of issues and
+pull requests, and ensure that the issue hasn't already been reported. If an
+issue has already been reported, but you have some new insight, please add
+a comment to the existing issue.
+
+Please read the FAQ in the README before creating any issues. A feature
+you desire may already exist and be documented, or the FAQ might explain
+how to solve a problem you have already.
+
+Please try and describe any issues reported with as much detail as you can
+provide about your Vim version, the linter you were trying to run, your
+operating system, or any other information you think might be helpful.
+
+Please describe your issue in clear, grammatically correct, and easy to
+understand English. You are more likely to see an issue resolved if others
+can understand you.
 
 <a name="pull-requests"></a>
 
-# 2. Creating Pull Requests
+# 3. Creating Pull Requests
 
-For code you write, make sure to credit yourself at the top of files you add, and probably those you modify. You can write
-some comments at the top of your VIM files.
+For code you write, make sure to credit yourself at the top of files you add,
+and probably those you modify. You can write some comments at the top of your
+VIM files.
 
 ```vim
 " Author: John Smith <john.smith@gmail.com>
-" Description: This file adds support for awesomelinter to the best language ever.
+" Description: This file adds support for awesomelinter for the best language ever.
 ```
 
 If you want to credit multiple authors, you can comma separate them.
@@ -33,34 +58,35 @@ If you want to credit multiple authors, you can comma separate them.
 " Author: John Smith <john.smith@gmail.com>, Jane Doe <https://jane-doe.info>
 ```
 
-# 2.1. Adding a New Linter
-
-If you add a new linter, look for existing handlers first in the [handlers.vim](autoload/ale/handlers.vim) file. One of the handlers
-there may already be able to handle your lines of output. If you find that your new linter replicates an existing error handler,
-consider pulling it up into the [handlers.vim](autoload/ale/handlers.vim) file, and use the generic handler in both places.
+<a name="adding-a-new-linter"></a>
 
-When you add a linter, make sure the language for the linter and the linter itself are present in the table in the
-[README.md](README.md) file and in the Vim [help file](doc/ale.txt). The programs and linters are sorted alphabetically in the
-table and list.
+# 3.i. Adding a New Linter
 
-# 2.2. Adding New Options
+If you add a new linter, look for existing handlers first in the
+[handlers.vim](autoload/ale/handlers.vim) file. One of the handlers there may
+already be able to handle your lines of output. If you find that your new
+linter replicates an existing error handler, consider pulling it up into the
+[handlers.vim](autoload/ale/handlers.vim) file, and use the generic handler in
+both places.
 
-If you add new options to the plugin, make sure to document those new options in the [README.md](README.md) file, and also
-in the [help file](doc/ale.txt). Follow the format of other options in each. Global options should appear in the README
-file, and in the relevant section in the help file, and options specific to a particular linter should go in the section
-for that linter.
+When you add a linter, make sure the language for the linter and the linter
+itself are present in the table in the [README.md](README.md) file and in the
+Vim [help file](doc/ale.txt). The programs and linters should be sorted
+alphabetically in the table and list.
 
-<a name="compiling"></a>
+<a name="adding-new-options"></a>
 
-# 3. Compiling the Windows stdin wrapper
+# 3.ii. Adding New Options
 
-To compile the stdin wrapper program for Windows, when updating the D program, you will need to compile the program with
-[LDC](https://github.com/ldc-developers/ldc) in release mode. Download and install the Community edition of Visual Studio
-from [the Visual Studio website](https://www.visualstudio.com/downloads/) first before installing LDC. LDC typically comes in
-a ZIP you can just extract somewhere.
+If you add new options to the plugin, make sure to document those new options
+in the [README.md](README.md) file, and also in the [help file](doc/ale.txt).
+Follow the format of other options in each. Global options should appear in the
+README file, and in the relevant section in the help file. Options specific
+to a particular linter should appear in the section for that linter.
 
-Make sure to compile with the 32-bit architecture flag, otherwise the EXE will not run on 32-bit machines.
+Linter options for customizing general argument lists should be named
+`g:ale_<filetype>_<linter>_options`, so that all linters can have similar
+global variable names.
 
-```
-ldc2 -m32 -Oz -release stdin_wrapper.d -of=stdin-wrapper.exe
-```
+Any options for linters should be set to some default value so it is always
+easy to see what the default is with `:echo g:ale...`.