Proofread Docs / Fix Formatting (#32)

* Proofread Aleph.im network node descriptions for clarity.

* Fix formatting

* Fix formatting of chains.md

* Add overview to index page

* Fix formatting of messages.md

* Fix formatting of overview.md

* Add instructions to run development server.

* Update Pipfile.lock

* Revert "Update Pipfile.lock"

This reverts commit c6cb644.

README.md

@@ -4,12 +4,18 @@ Based on _Material for MkDocs_
 
 https://squidfunk.github.io/mkdocs-material/getting-started/
 
-## 
+## Install from source
 
 ```shell
 pipenv install --dev
 ```
 
+## Run the development server
+By running the following command, you will get a server that will automatically update the docs pages whenever you edit the sources.
+```shell
+pipenv run mkdocs serve
+```
+
 ## JSON schemas
 
 Using a Jetbrain IDE, you can manage loading JSON schemas using the Languages & Frameworks | Schemas and DTDs | Remote

docs/index.md

@@ -5,8 +5,9 @@ information, resources, and tools to get started with the Aleph.im project.
 
 ## Where to start?
 
-- Use our [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs
-- Follow a [tutorial to run Python code on aleph.im](guides/python/getting_started.md).
+- Read the [Overview](./overview.md) to understand what Aleph.im is and how it works.
+- Use our [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs.
+- Follow a [Tutorial to run Python code on aleph.im](guides/python/getting_started.md).
 - Become part of the network by managing a [Core Channel Node](nodes/core/index.md) or a [Compute Resource Node](./nodes/compute.md).
 - Chat on our [Telegram group](https://t.me/alephim).
 - Engage on our [Discourse Channel](https://community.aleph.im/)

docs/overview.md

@@ -5,36 +5,37 @@
 Aleph.im is an open-source off-chain P2P (peer-to-peer) network. It offers decentralized volumes and blockchain indexing, function execution and VM provisioning, as well as a DID (decentralized identity) framework.
 Aleph.im also includes bridges to many major blockchain networks, such as Ethereum (or any EVM-compatible blockchain), Tezos and Solana, to enable smart contracts access to the resources and hosted on the Aleph.im network.
 
-The Aleph.im project has the following components :
-- The Aleph peer-to-peer network, comprised of [Compute Resource Nodes, or CRNs](./nodes/compute.md) and [Core Channel Nodes, or CCNs](./nodes/core/index.md)
-- [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs to integrate Aleph.im's decentralized compute and storage solutions into your project
-- A [Python CLI tool](https://aleph-client.readthedocs.io/en/latest/) to interact with the Aleph.im network directly from a terminal
-- A [web GUI dashboard](https://console.aleph.im/)
-- An [Explorer](https://explorer.aleph.im/)
+### The Aleph.im project has the following components:
+
+* The Aleph peer-to-peer network, comprised of [Compute Resource Nodes or CRNs](./nodes/compute.md) and [Core Channel Nodes, or CCNs](./nodes/core/index.md)
+* [Python](./libraries/python.md) and [Typescript](./libraries/typescript.md) SDKs to integrate Aleph.im's decentralized compute and storage solutions into your project
+* A [Python CLI tool](https://aleph-client.readthedocs.io/en/latest/) to interact with the Aleph.im network directly from a terminal
+* A [web GUI dashboard](https://console.aleph.im/)
+* An [Explorer](https://explorer.aleph.im/)
 
 ## The Aleph.im network
 
 ![The Aleph.im network](./network-overview.svg)
 
-The Aleph.im network is composed of 2 sets of nodes :<br>
- - [CCNs](./nodes/core/index.md), the backbone of the P2P network. They serve as an entrypoint into the network through an API (similar to a blockchain node's RPC).<br>
- - [CRNs](./nodes/compute.md), responsible for the actual compute and storage available on Aleph.im. CRNs must be manually tied to a single CCN, and each CCN can (and is incentivized to) be tied to up to 3 CRNs.<br>
-<br>
+The Aleph.im network is composed of 2 sets of nodes:
+
+* [CCNs](./nodes/core/index.md), the backbone of the P2P network. They serve as an entry point into the network through an API (similar to a blockchain node's RPC).
+* [CRNs](./nodes/compute.md), responsible for the actual compute and storage available on Aleph.im. CRNs must be tied manually to a single CCN, and each CCN is incentivized to tie up to 3 CRNs.
 
 ### Messages
-In Aleph.im terminology, a "message" is similar to a "transaction" for a blockchain: it is a set of data sent by an end user, propagated through the entire peer-to-peer network.<br>
-A message can be generated using either the [python](./libraries/python.md) or [typescript](./libraries/typescript.md) SDKs, or through the [aleph-client](https://aleph-client.readthedocs.io/en/latest/) or the [web dashboard](https://console.aleph.im/).<br>
-These messages can contain several different instruction, such as reading or writing [posts](https://aleph-client.readthedocs.io/en/latest/content/posts.html#), [programs/functions](./computing/persistent.md), or [indexing data](./frameworks/indexer.md) created on external blockchains.<br>
+In Aleph.im terminology, a "message" is similar to a "transaction" for a blockchain: it is a set of data sent by an end user, propagated through the entire peer-to-peer network.
+A message can be generated using either the [python](./libraries/python.md) or [typescript](./libraries/typescript.md) SDKs, or through the [aleph-client](https://aleph-client.readthedocs.io/en/latest/) or the [web dashboard](https://console.aleph.im/).
+These messages can contain several different instructions, such as reading or writing [posts](https://aleph-client.readthedocs.io/en/latest/content/posts.html#), [programs/functions](./computing/persistent.md), or [indexing data](./frameworks/indexer.md) created on external blockchains.
 
 ### Payment
-While Aleph is not a blockchain itself, it uses the ALEPH token hosted on Ethereum to manage users payment and offer network integrity and workload execution rewards to node operators. Because of this, you must have an EVM-compatible wallet (such as Metamask) provisionned with some ALEPH tokens to write to the network.<br>
-<br>
+While Aleph is not a blockchain. It uses the ALEPH token hosted on Ethereum to manage users' payments and offer network integrity and workload execution rewards to node operators. Because of this, you must have an EVM-compatible wallet (such as Metamask) provisioned with some ALEPH tokens to write to the network.
 
 ### Example
-Let's take the example of a user who wants to run a program on the Aleph.im network :<br>
-1) The user makes sure to have an Ethereum wallet with at least 2000 ALEPH tokens<br>
-2) The user writes and sends a message using either the aleph python client, one of the SDKs, or the web dashboard<br>
-3) The message arrives at a CCN, which then broadcasts that message to all CCNs in the network<br>
-4) The "program" workload scheduled by the user's message gets assigned to one of the CCNs<br>
-5) The assigned CCN now assigns that workload onto one of its CRNs<br>
-6) The assigned CRN creates a micro-vm that will execute the user's requested workload.<br>
+Let's take the example of a user who wants to run a program on the Aleph.im network:
+
+1. The user makes sure to have an Ethereum wallet with at least 2000 ALEPH tokens
+2. The user writes and sends a message using either the aleph python client, one of the SDKs, or the web dashboard
+3. The message arrives at a CCN, which then broadcasts that message to all CCNs in the network
+4. The "program" workload scheduled by the user's message gets assigned to one of the CCNs
+5. The assigned CCN now assigns that workload onto one of its CRNs
+6. The assigned CRN creates a micro-vm executing the user's requested workload.

docs/protocol/chains.md

@@ -6,20 +6,20 @@ The support of a chain consists in the functionalities below.
 The support of a chain may be partial, when only some of these 
 functionalities are supported.
 
-1. **Message signature**: \
+1. **Message signature**:
    Messages on the aleph.im network must be signed using asymmetric a user's private key.
    Different chains may use public-key cryptography differently, resulting in different methods
    of verifying message signatures.
-2. **Wallet support** \
+2. **Wallet support**:
    Interacting with aleph.im in a browser and signing messages requires the use of a Wallet application. 
    These applications are often specific to one or a few chains.
-3. **Token availability**: \
+3. **Token availability**:
    Allocating resources on the aleph.im network relies on a fungible onchain token.
    Exchanging that token on a blockchain requires that token to be available on that chain first. 
-4. **Balance support** \
+4. **Balance support**:
    The aleph.im network needs to be aware of user's tokens on each supported chain in order to allow
    users to allocate resources on the network. Some services are not available without balance support.
-5. **Staking support**: \
+5. **Staking support**:
    Users can help securing the aleph.im network by holding tokens and _staking_ them on 
    [Core Channel Nodes](../nodes/core/index.md) they consider trustworthy. The aleph.im network
    interacts with blockchains to achieve this mechanism.

docs/protocol/messages.md

@@ -5,6 +5,7 @@ All the data that transits on the network is represented by aleph.im messages th
 all the possible operations on the network.
 
 With aleph.im messages, you can, for example:
+
 * store files
 * pin content on IPFS
 * create decentralized programs