Merge pull request #5 from oceanprotocol/feature/some-more-docs

More docs: introduction, marketplace help, etc.

content/concepts/introduction.md

@@ -3,4 +3,20 @@ title: Introduction
 description: Get up to speed with Ocean Protocol
 ---
 
-What is Ocean Protocol?
+## What is Ocean Protocol?
+
+It's a decentralized data exchange protocol to unlock data for artificial intelligence (AI).
+
+While vast amounts of data are generated each year, data exchange and analysis have been hampered due largely to concerns over trust and security. Currently, many organizations have data but do not have the trusted and secure means to share it. Without data, AI cannot advance and be applied to solve problems and ultimately improve lives. More pressing is the fact that today, only a handful of companies have both AI and data capacities, and if data remains locked up, these companies could very well govern the development of AI and thereby our future.
+
+Through blockchain technology and tokens, Ocean Protocol connects data providers and consumers, allowing data to be shared while guaranteeing traceability, transparency, and trust for all stakeholders involved. Ocean Protocol is designed to give data owners control over their data assets and prevent them from being locked in to any single marketplace.
+
+By bringing together decentralized blockchain technology, a data sharing framework, and an ecosystem for data and related services, Ocean Protocol is committed to kick-starting a new Data Economy that touches every single person, company and device, giving power back to data owners, enabling people to reap value from data to better our world.
+
+There are more details on the
+[Ocean Protocol home page](https://oceanprotocol.com/),
+and in the whitepapers:
+
+* [Technical Whitepaper](https://oceanprotocol.com/tech-whitepaper.pdf)
+* [Business Whitepaper](https://oceanprotocol.com/business-whitepaper.pdf)
+* [Reference Marketplace Framework](https://oceanprotocol.com/marketplace-framework.pdf)

content/concepts/terminology.md

@@ -17,11 +17,14 @@ Someone who wants assets. An example is a data scientist working at an economic
 
 ## Marketplace
 
-A service where publishers can list what assets they have, and consumers can see what's available then buy it (or get it for free).
+A service where publishers can list what assets they have, and consumers can see what's available then buy it (or get it for free). The Ocean network supports many marketplaces.
 
 ## Keeper
 
-A computer running a blockchain client (i.e. a blockchain node) where the associated blockchain network is running the Ocean Protocol keeper contracts (smart contracts).
+A computer running a blockchain client (i.e. a blockchain node)
+where the associated blockchain network is running the
+[Ocean Protocol keeper contracts](https://github.com/oceanprotocol/keeper-contracts)
+(smart contracts).
 
 ## Aquarius
 
@@ -33,12 +36,12 @@ Ocean-specific software to help publishers manage consumer access to their asset
 
 ## Secret Store
 
-[Parity Secret Store](https://wiki.parity.io/Secret-Store).
+[Parity Secret Store](https://wiki.parity.io/Secret-Store): software for distributed key pair generation, distributed key storage, and threshold retrieval.
 
-## Squid
+## squid-py, squid-js, squid-java, etc.
 
-A set of software libraries to interact with Ocean network participants, including Keepers, Aquarius, Brizo, and Secret Store. The initial libraries are in Python, JavaScript and Java.
+Software libraries used by applications to interact with Ocean nodes, including Keepers, Aquarius nodes, Brizo nodes, etc.
 
 ## Pleuston
 
-An example marketplace frontend implemented using React and Squid-JavaScript.
+An example marketplace website frontend implemented using React and squid-js.

content/setup/keeper.md

@@ -1,3 +1,5 @@
 ---
 title: Set Up a Keeper
 ---
+
+This page is a placeholder for now.

content/setup/marketplace.md

@@ -1,3 +1,43 @@
 ---
 title: Set Up a Marketplace
 ---
+
+If you want to set up a marketplace for the Ocean network, then you could start by running the following tech stack:
+
+1. Pleuston
+1. Aquarius
+1. A database for Aquarius
+
+Then you could modify that stack to better suit your needs.
+Let's take a closer look inside each of those components.
+
+## Pleuston
+
+Pleuston is an example Ocean marketplace written in JavaScript using React and Redux.
+It uses the squid-js library to interact with Ocean network services, such as Keepers, Brizo nodes, Secret Stores, and your own Aquarius node.
+Pleuston runs entirely in the browser, i.e. Pleuston has no server-side part. It communicates directly with Keepers etc.
+
+You _could_ build an Ocean marketplace with a browser-side frontend and a server-side part.
+For example, the server-side part could be written in Python and it could use the squid-py library.
+Currently, there is no explicit example of how to do that, but there are examples of how to use squid-py, e.g. from IPython running in a Jupyter notebook.
+See the Tutorials section.
+
+You could even write an entirely server-side marketplace with a command-line interface, but let's not get carried away.
+
+Note: There's also a squid-java library but it's currently not as full-featured as squid-js and squid-py.
+
+## Aquarius
+
+Aquarius is an application used by Marketplaces to store, update, read and delete metadata about assets. The Squid libraries all know how to talk to Aquarius, so you don't need to think about it or its API too much. You just need to make sure you have Aquarius running on a server somewhere.
+
+TODO: Link to instructions.
+
+## Database for Aquarius
+
+At the time of writing, Aquarius worked with three databases:
+
+* MongoDB
+* Elasticsearch
+* BigchainDB
+
+TODO: Outline the pros and cons of each database.

content/setup/publisher.md

@@ -1,3 +1,5 @@
 ---
 title: Publish Data or Services
 ---
+
+This page is a placeholder for now.

content/tutorials/jupyter.md

@@ -2,4 +2,4 @@
 title: Example Jupyter Notebooks to Interact with the Ocean Network
 ---
 
-(Mantaray)
+For now, check out [the Mantaray repository](https://github.com/oceanprotocol/mantaray). In the future, we hope to have live online Jupyter notebooks.