reform readme

docs/README.md

@@ -1,10 +1,36 @@
 # Documentation
 
-All Blockstack software documentation is in this directory. 
+All Blockstack software documentation is either in this directory, or linked
+from this file.
 
-## Quick Links
+## FAQs
 
-* [Basic command-line usage](https://github.com/blockstack/blockstack-core/blob/master/docs/basic_usage.md)
-* [Advanced command-line usage](https://github.com/blockstack/blockstack-core/blob/master/docs/advanced_usage.md)
-* [Glossary of Terms](https://github.com/blockstack/blockstack-core/blob/master/docs/glossary.md)
-* [How to link your OpenBazaar Store to your Blockstack ID](https://github.com/blockstack/blockstack-core/blob/master/docs/openbazaar.md)
+* [General FAQ](https://blockstack.org/faq)
+* [Technical FAQ](faq_technical.md)
+
+## System Design and Implementation
+
+* [Blockstack Naming Service](blockstack_naming_service.md) (start here)
+* [Atlas Peer Network](atlas_network.md)
+* [Gaia Storage System](https://github.com/blockstack/gaia)
+* [Transaction Formats](wire-format.md)
+* [Glossary](glossary.md)
+
+## Command-line Documentation
+
+* [CLI walkthrough](basic_usage.md)
+* [CLI reference](cli.md)
+
+## Developer Documentation
+
+* [blockstack.js](https://github.com/blockstack/blockstack.js)
+* [Blockstack Browser](https://github.com/blockstack/blockstack-browser)
+* [Blockstack Core API](https://core.blockstack.org)
+* [Integration Test Framework](../integration-tests)
+
+## Advanced Topics
+
+* [How to Create a Namespace](namespace_creation.md)
+* [How to link your OpenBazaar Store to your Blockstack ID](openbazaar.md)
+* [How to build a Profile Search Index](search.md)
+* [How to Run a Blockstack Subdomain Registrar](subdomains.md)