From 0c1affe43ee56da6ad481724f53ba92e0f41a990 Mon Sep 17 00:00:00 2001
From: Chris Ward <chriswhward@gmail.com>
Date: Mon, 12 Nov 2018 11:46:23 +0100
Subject: [PATCH] Begin documentation style guide

Add pragma to documentation style guide

Fix formatting and add link

Move docs style guide

Changes from review
---
 docs/contributing.rst | 79 +++++++++++++++++++++++++++++++++++++++++++
 docs/index.rst        |  2 ++
 docs/style-guide.rst  |  6 ----
 3 files changed, 81 insertions(+), 6 deletions(-)

diff --git a/docs/contributing.rst b/docs/contributing.rst
index 8d95b63b5..5e9308b50 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -326,3 +326,82 @@ escaping and without iterated replacements. An area can be delimited by ``<#name
 by as many concatenations of its contents as there were sets of variables supplied to the template system,
 each time replacing any ``<inner>`` items by their respective value. Top-level variables can also be used
 inside such areas.
+
+.. _documentation-style:
+
+Documentation Style Guide
+=========================
+
+The following are style recommendations specifically for documentation
+contributions to Solidity.
+
+English Language
+----------------
+
+Use English, with British English spelling preferred, unless using project or brand names. Try to reduce the usage of
+local slang and references, making your language as clear to all readers as possible. Below are some references to help:
+
+* `Simplified technical English <https://en.wikipedia.org/wiki/Simplified_Technical_English>`_
+* `International English <https://en.wikipedia.org/wiki/International_English>`_
+* `British English spelling <https://en.oxforddictionaries.com/spelling/british-and-spelling>`_
+
+
+.. note::
+
+    While the official Solidity documentation is written in English, there are community contributed :ref:`translations`
+    in other languages available.
+
+Title Case for Headings
+-----------------------
+
+Use `title case <http://titlecase.com>`_ for headings. This means capitalise all principal words in
+titles, but not articles, conjunctions, and prepositions unless they start the
+title.
+
+For example, the following are all correct:
+
+* Title Case for Headings
+* For Headings Use Title Case
+* Local and State Variable Names
+* Order of Layout
+
+Expand Contractions
+-------------------
+
+Use expanded contractions for words, for example:
+
+* "Do not" instead of "Don't".
+* "Can not" instead of "Can't".
+
+Active and Passive Voice
+------------------------
+
+Active voice is typically recommended for tutorial style documentation as it
+helps the reader understand who or what is performing a task. However, as the
+Solidity documentation is a mixture of tutorials and reference content, passive
+voice is sometimes more applicable.
+
+As a summary:
+
+* Use passive voice for technical reference, for example language definition and internals of the Ethereum VM.
+* Use active voice when describing recommendations on how to apply an aspect of Solidity.
+
+For example, the below is in passive voice as it specifies an aspect of Solidity:
+
+  Functions can be declared ``pure`` in which case they promise not to read
+  from or modify the state.
+
+For example, the below is in active voice as it discusses an application of Solidity:
+
+  When invoking the compiler, you can specify how to discover the first element
+  of a path, and also path prefix remappings.
+
+Common Terms
+------------
+
+* "Function parameters" and "return variables", not input and output parameters.
+
+Code Examples
+-------------
+
+* Ensure that all code examples begin with a ``pragma`` version that spans the largest where the contract code is valid. For example ``pragma solidity >=0.4.0 <0.6.0;``.
\ No newline at end of file
diff --git a/docs/index.rst b/docs/index.rst
index f0011b916..0ec500e7f 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -52,6 +52,8 @@ If you have any questions, you can try searching for answers or asking on the
 
 Ideas for improving Solidity or this documentation are always welcome, read our :doc:`contributors guide <contributing>` for more details.
 
+.. _translations:
+
 Translations
 ------------
 
diff --git a/docs/style-guide.rst b/docs/style-guide.rst
index bf1be93ef..dcbfc486a 100644
--- a/docs/style-guide.rst
+++ b/docs/style-guide.rst
@@ -1088,12 +1088,6 @@ Avoiding Naming Collisions
 This convention is suggested when the desired name collides with that of a
 built-in or otherwise reserved name.
 
-
-General Recommendations
-=======================
-
-TODO
-
 .. _natspec:
 
 *******