Better READMEs

Author: alcueca

README.md

@@ -17,7 +17,29 @@
     </div>
 </div>
 
-> HQ20/contracts is a Solidity project with contracts, libraries and examples to help you build fully-featured distributed applications for the real world.
+> HQ20/contracts is a Solidity project with contracts, libraries and examples to help you build fully-featured distributed applications for the real world. The contracts are expected to be used as smart contract patterns for you to draw inspiration from, and for that purpose they have ben kept deliberately simple. If you decide to reuse the contracts, or to copy and paste code in them, make sure that you look for and close the vulnerabilities. If you plan to go to the mainnet, please get a third party audit done.
+
+## In a Nutshell
+
+At the time of this writing (`May 2020`), this are the contents of this repository:
+
+```
+contracts ──┬─── access        - Access Control Contracts, some of them built on top of `AccessControl.sol`
+            ├─── classifieds   - Example of a decentralized classifieds market for ERC721
+            ├─── dao           - Example of building a decentralized venture capital fund
+            ├─── drafts        - Stuff not yet ready for prime-time
+            ├─── energy        - Example of building a decentralized market for energy distribution
+            ├─── exchange      - The Uniswap decentralized market contracts, with solidity tests
+            ├─── introspection - Example of using ERC165 to verify contract types before casting
+            ├─── issuance      - Example of an ICO, can be used as well for share issuances
+            ├─── lists         - Reusable implementations of different types of linked lists
+            ├─── math          - Reusable implementation of a lightweight fixed point math library
+            ├─── state         - Reusable implementation of a fully-featured state machine
+            ├─── test          - Implementations of contracts for testing of interanl functions
+            ├─── token         - Token implementations, including a reusable dividend-bearing ERC20
+            ├─── utils         - Reusable library to cast between `uint` and `int`.
+            └─── voting        - Example implementations of token-based and address-based votings
+```
 
 ## Installation
 
@@ -57,34 +79,6 @@ For contracts that are used for testing of libraries or internal methods there i
 
 The `test` directory replicates the structure of the `contracts` directory.
 
-At the time of this writing (`Feb 2020`), this is the directory structure:
-
-```
-contracts ──┬─── access
-            │
-            ├─── classifieds
-            │
-            ├─── drafts ───────┬─── classifieds
-            │                  ├─── issuance
-            |                  ├─── lists ──────────── mocks
-            |                  ├─── strings
-            |                  ├─── token
-            |                  └─── voting
-            │
-            ├─── examples ─────┬─── access
-            │                  ├─── dao
-            │                  ├─── energy
-            │                  └─── introspection
-            │
-            ├─── exchange
-            ├─── issuance
-            ├─── lists 
-            ├─── state
-            ├─── test
-            ├─── token
-            └─── utils
-```
-
 ## Contributing
 Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
 

contracts/access/README.md

@@ -2,6 +2,8 @@
 
 This is an Ethereum project that implements different access control structures on top of OpenZeppelin's AccessControl.sol.
 
+For a longer explanation of some of the contracts here, [please read this article](https://medium.com/coinmonks/how-to-use-accesscontrol-sol-9ea3a57f4b15?source=friends_link&sk=c274faededcbb71c6a211f33de4cf5c9).
+
 
 # Community
 

contracts/classifieds/README.md

@@ -2,6 +2,8 @@
 
 This is an Ethereum project which implements a classifieds board.
 
+For a longer explanation of the contracts here, [please read this article](https://medium.com/coinmonks/how-to-implement-an-erc721-market-f805959ddcf?source=friends_link&sk=5a9c2bb92a2bb92403a32e389e933613).
+
 ## Description
 
 A classifieds board can be used to open and close trades between ERC20 and ERC721 tokens.

contracts/energy/README.md

@@ -1,6 +1,9 @@
 # EnergyMarket
 
-This is an Ethereum project that implements an Energy Market
+This is an Ethereum project that implements an Energy Market.
+
+For a longer explanation of the contracts here, [please read this article](https://medium.com/coinmonks/how-to-build-an-energy-market-on-a-blockchain-c43b0cfc2d12?source=friends_link&sk=75fd59c0488c354782985321aa2919cb).
+
 
 ## Usage
 

contracts/lists/README.md

@@ -2,6 +2,8 @@
 
 This is an Ethereum project that implements singly and doubly linked lists (https://en.wikipedia.org/wiki/Linked_list).
 
+For a longer explanation of some of the contracts here, [please read this article](https://medium.com/coinmonks/a-linked-list-implementation-for-ethereum-a2915bf8122f?source=friends_link&sk=be8889a651eed8193b1c4421a50484dd).
+
 # Terminology
 Object: Objects are linked to each other and together they are a Linked List
 Head: The first object in the list. No other object points to the head.