From b75859ff150200e83d74f5cef2504ab805d2bf35 Mon Sep 17 00:00:00 2001 From: Chris Ward Date: Mon, 17 Sep 2018 17:16:05 +0200 Subject: Begin overhaul of documentation index --- docs/index.rst | 64 ++++++++++++++++++++++++++++------------------------------ 1 file 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 `_ - (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 ` written +in Solidity. When you are ready for more detail, we recommend you read the +:doc:`"Solidity by Example" ` and :doc:`"Solidity in Depth" ` sections to learn the core concepts of the language. + +For further reading, try :ref:`the basics of blockchains ` +and details of the :ref:`Ethereum Virtual Machine `. + +.. hint:: + You can always try out code examples in your browser with the + `Remix IDE `_. 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 `_, or our `gitter channel `_. + +Ideas for improving Solidity or this documentation are always welcome, read our :doc:`contributors guide ` 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 `_ (in progress) * `Spanish `_ @@ -46,25 +63,6 @@ with varying degrees of completeness and up-to-dateness. The English version sta * `Korean `_ (in progress) * `French `_ (in progress) -Language Documentation ----------------------- - -On the next pages, we will first see a :ref:`simple smart contract ` written -in Solidity followed by the basics about :ref:`blockchains ` -and the :ref:`Ethereum Virtual Machine `. - -The next section will explain several *features* of Solidity by giving -useful :ref:`example contracts `. -Remember that you can always try out the contracts -`in your browser `_! - -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 `_ -site, or come to our `gitter channel `_. -Ideas for improving Solidity or this documentation are always welcome! - Contents ======== -- cgit v1.2.3