From a7c6279b147e749cd84a57cc19180d5f9bddfc10 Mon Sep 17 00:00:00 2001
From: apense <apense@users.noreply.github.com>
Date: Wed, 1 Jul 2015 12:53:37 -0400
Subject: [PATCH 1/3] Added documentation guidelines (brief)

---
 contributing.rst | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)

diff --git a/contributing.rst b/contributing.rst
index 48f0dbf00e..a952b8e74a 100644
--- a/contributing.rst
+++ b/contributing.rst
@@ -135,6 +135,45 @@ overloading so for routines the latter variant is better.
 pragma in the manual.
 
 
+Documentation
+=============
+
+When contributing new procedures, be sure to add documentation, especially if
+the procedure is exported from the module. Documentation begins on the line
+following the ``proc`` definition, and is prefixed by ``##`` on each line.
+
+Code examples are also encouraged. The RST syntax Nim uses has a special syntax
+for including examples.
+
+.. code-block:: nim
+
+  proc someproc*(): string =
+    ## returns "something"
+    ##
+    ## .. code-block:: nim
+    ##
+    ##  echo someproc() # "something"
+    result = "something" # single-hash comments do not produce documentation
+
+The ``.. code-block:: nim`` followed by a newline and an indentation instructs the 
+``nim doc`` and ``nim doc2`` commands to produce syntax-highlited example code with 
+the documentation.
+
+When forward declaration is used, the documentation should be included with the
+first appearance of the proc.
+
+.. code-block:: nim
+
+  proc hello*(): string
+    ## Documentation goes here
+  proc nothing() = discard
+  proc hello*(): string =
+    ## This documentation is ignored
+    echo "hello"
+
+Capitalization of the first letter on the first line is optional. As a general
+rule, if the documentation begins with a full sentence, capitalize it;
+otherwise, a lowercase letter is preferred.
 
 The Git stuff
 =============

From 13dd7922aaa62b459478b7049b2bd4e85df13dff Mon Sep 17 00:00:00 2001
From: apense <apense@users.noreply.github.com>
Date: Wed, 1 Jul 2015 13:00:01 -0400
Subject: [PATCH 2/3] Clarified and fixed typo

---
 contributing.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/contributing.rst b/contributing.rst
index a952b8e74a..5b86cf802a 100644
--- a/contributing.rst
+++ b/contributing.rst
@@ -142,8 +142,8 @@ When contributing new procedures, be sure to add documentation, especially if
 the procedure is exported from the module. Documentation begins on the line
 following the ``proc`` definition, and is prefixed by ``##`` on each line.
 
-Code examples are also encouraged. The RST syntax Nim uses has a special syntax
-for including examples.
+Code examples are also encouraged. The RestructuredText Nim uses has a special 
+syntax for including examples.
 
 .. code-block:: nim
 
@@ -156,7 +156,7 @@ for including examples.
     result = "something" # single-hash comments do not produce documentation
 
 The ``.. code-block:: nim`` followed by a newline and an indentation instructs the 
-``nim doc`` and ``nim doc2`` commands to produce syntax-highlited example code with 
+``nim doc`` and ``nim doc2`` commands to produce syntax-highlighted example code with 
 the documentation.
 
 When forward declaration is used, the documentation should be included with the

From c4fb1246d1c8768aff26aaae50c713da8580c236 Mon Sep 17 00:00:00 2001
From: apense <apense@users.noreply.github.com>
Date: Thu, 2 Jul 2015 15:21:24 -0400
Subject: [PATCH 3/3] Updated to capitalized, imperative

---
 contributing.rst | 26 ++++++++++++++++++++------
 1 file changed, 20 insertions(+), 6 deletions(-)

diff --git a/contributing.rst b/contributing.rst
index 5b86cf802a..68b706c735 100644
--- a/contributing.rst
+++ b/contributing.rst
@@ -148,7 +148,7 @@ syntax for including examples.
 .. code-block:: nim
 
   proc someproc*(): string =
-    ## returns "something"
+    ## Return "something"
     ##
     ## .. code-block:: nim
     ##
@@ -165,15 +165,29 @@ first appearance of the proc.
 .. code-block:: nim
 
   proc hello*(): string
-    ## Documentation goes here
+    ## Put documentation here
   proc nothing() = discard
   proc hello*(): string =
-    ## This documentation is ignored
+    ## Ignore this
     echo "hello"
 
-Capitalization of the first letter on the first line is optional. As a general
-rule, if the documentation begins with a full sentence, capitalize it;
-otherwise, a lowercase letter is preferred.
+The preferred documentation style is to begin with a capital letter and use
+the imperative (command) form. That is, between:
+
+.. code-block:: nim
+
+  proc hello*(): string =
+    # Return "hello"
+    result = "hello"
+or
+
+.. code-block:: nim
+
+  proc hello*(): string =
+    # says hello
+    result = "hello"
+  
+the first is preferred.
 
 The Git stuff
 =============