Merge pull request #5289 from ethereum/docs-index-overhaul

DOCS: Updates to docs index file

1 files changed, 31 insertions, 33 deletions

diff --git a/docs/index.rst b/docs/index.rst
index 17abf4b2..ed931163 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -19,26 +19,43 @@ user-defined types among other features.
 With Solidity you can create contracts for uses such as voting, crowdfunding, blind auctions,
 and multi-signature wallets.
 
-.. note::
-    The best way to try out Solidity right now is using
-    `Remix <https://remix.ethereum.org/>`_
-    (it can take a while to load, please be patient). Remix is a web browser
-    based IDE that allows you to write Solidity smart contracts, then deploy
-    and run the smart contracts.
+Language Documentation
+----------------------
+
+If you are new to the concept of smart contracts we recommend you start with
+:ref:`an example smart contract <simple-smart-contract>` written
+in Solidity. When you are ready for more detail, we recommend you read the
+:doc:`"Solidity by Example" <solidity-by-example>` and :doc:`"Solidity in Depth" <solidity-in-depth>` sections to learn the core concepts of the language.
+
+For further reading, try :ref:`the basics of blockchains <blockchain-basics>`
+and details of the :ref:`Ethereum Virtual Machine <the-ethereum-virtual-machine>`.
+
+.. hint::
+  You can always try out code examples in your browser with the
+  `Remix IDE <https://remix.ethereum.org>`_. Remix is a web browser based IDE
+  that allows you to write Solidity smart contracts, then deploy and run the
+  smart contracts. It can take a while to load, so please be patient.
 
 .. warning::
-    Since software is written by humans, it can have bugs. Thus, also
-    smart contracts should be created following well-known best-practices in
-    software development. This includes code review, testing, audits and correctness proofs.
-    Also note that users are sometimes more confident in code than its authors.
-    Finally, blockchains have their own things to watch out for, so please take
-    a look at the section :ref:`security_considerations`.
+    As humans write software, it can have bugs. You should follow established
+    software development best-practices when writing your smart contracts, this
+    includes code review, testing, audits, and correctness proofs. Smart contract
+    users are sometimes more confident with code than their authors, and
+    blockchains and smart contracts have their own unique issues to
+    watch out for, so before working on production code, make sure you read the
+    :ref:`security_considerations` section.
+
+If you have any questions, you can try searching for answers or asking on the
+`Ethereum Stackexchange <https://ethereum.stackexchange.com/>`_, or our `gitter channel <https://gitter.im/ethereum/solidity/>`_.
+
+Ideas for improving Solidity or this documentation are always welcome, read our :doc:`contributors guide <contributing>` for more details.
 
 Translations
 ------------
 
-This documentation is translated into several languages by community volunteers
-with varying degrees of completeness and up-to-dateness. The English version stands as a reference.
+Community volunteers help translate this documentation into several languages.
+They have varying degrees of completeness and up-to-dateness. The English
+version stands as a reference.
 
 * `Simplified Chinese <http://solidity-cn.readthedocs.io>`_ (in progress)
 * `Spanish <https://solidity-es.readthedocs.io>`_
@@ -46,25 +63,6 @@ with varying degrees of completeness and up-to-dateness. The English version sta
 * `Korean <http://solidity-kr.readthedocs.io>`_ (in progress)
 * `French <http://solidity-fr.readthedocs.io>`_ (in progress)
 
-Language Documentation
-----------------------
-
-On the next pages, we will first see a :ref:`simple smart contract <simple-smart-contract>` written
-in Solidity followed by the basics about :ref:`blockchains <blockchain-basics>`
-and the :ref:`Ethereum Virtual Machine <the-ethereum-virtual-machine>`.
-
-The next section will explain several *features* of Solidity by giving
-useful :ref:`example contracts <voting>`.
-Remember that you can always try out the contracts
-`in your browser <https://remix.ethereum.org>`_!
-
-The fourth and most extensive section will cover all aspects of Solidity in depth.
-
-If you still have questions, you can try searching or asking on the
-`Ethereum Stackexchange <https://ethereum.stackexchange.com/>`_
-site, or come to our `gitter channel <https://gitter.im/ethereum/solidity/>`_.
-Ideas for improving Solidity or this documentation are always welcome!
-
 Contents
 ========