Update API descriptions

api/docs/README.md

@@ -4,7 +4,7 @@
 
 This notes are a fast "how to" of how to document a new vocdoni node endpoint. 
 
-- Before merge any new endpoint some tags have to be added to the endpoint:
+- Before you can merge any new endpoint some tags have to be added to the endpoint:
 
 ```
 //    @Tags           Accounts

api/docs/descriptions/accountSetHandler.md

@@ -1,5 +1,4 @@
-It register an account to the blockchain including IPFS metadata upload. 
+Register an account to the blockchain, including metadata upload to IPFS. 
 
 - Requires a signed protobuf transaction on the body to perform the operation.
-- Metadata is not required, but if no metadata is provided the account won't be listed on 
-[/chain/organizations](organizations-list) endpoint. Check there to read about differences between an account and a organization.
+- Metadata is not required, but if no metadata is provided the account won't be listed on the [/chain/organizations](organizations-list) endpoint. Check there to read about differences between an account and a organization.

api/docs/descriptions/api.md

@@ -1,13 +1,15 @@
-The Vocdoni API is a REST API that substitutes the previous RPCs in order to make it easier for  developers/integrators to build on top of the voting protocol. This API facilitates creating votings using Vocdoni, without the hassle of learning a complex blockchain platform, allowing to perform all the features that enable the voting protocol such as creating an account, entity, voting process, census & vote, abstracting as much as possible the complexity and offering simple and straightforward methods to perform those actions. 
 
-You can review the API endpoints documentation in this section, the main entities are:
+The Vocdoni API is a REST API that substitutes the previous RPCs in order to make it easier for  developers/integrators to build on top of the voting protocol. This API facilitates the creation of voting processes with Vocdoni, without the hassle of integrating with a complex distributed stack with blockchain components. The API allows integrators to perform all the features enabled by the Vocdoni voting protocol, such as creating accounts, organizations, voting processes, and censuses, as well as casting votes. The API is designed to abstract away the complexity of the Vocdoni protocol as much as possible, offering a simple and straightforward way to performing these actions. 
 
-- [**Chain**](chain): The Vocdoni blockchain is named Vochain. It is a Byzantine fault-tolerant network based on Tendermint that executes the Vocdoni Protocol logic represented as a state machine. Its main purpose is to register votes in a  decentralized and verifiable format. In those endpoints, you can consult the state of the chain, transactions costs,  list organizations and get more Vochain info.
-- [**Accounts**](accounts): Identified by an Ethereum like address. An account can create and manage elections, transfer tokens, give power to other accounts on his behalf (delegates) and manage its metadata.
-- [**Elections**](elections): Is a rule-set of options and requirements for creating a process in which people vote a series of options. To know more about the params of an election and its lifecycle go [here](../get-started/intro#23-elections). In this section you will find all information related to an election as its information, election keys, submitted votes & how to create a new election.
-- [**Censuses**](censuses): The census is a key component of any voting process. It specifies the set of users (identified by a public key or address) eligible for participating in an election. To understand more about the Censuses you can check [here](../get-started/intro#21-the-census). Here you will be able to get censuses information like the Merkle root, total weight & size, import/export the censuses and create new ones.
-- [**Votes**](votes): All the information related to the vote issued by a participant in a vote, you can check the validity of the vote, consult your information and send a vote.
-- [**SIK**](sik): The Secret Identity Key is a user-generated piece of information that proves the user's identity without revealing it. It is the hash of the user's address, the signature of a public message and an optional secret part. It is used to ensure anonymous voting. All registered accounts or anonymous voters must register a SIK, and they are all stored in a Merkle tree. The `/siks` endpoints help to generate a proof of membership, get the current valid SIK roots, or check if an account has a valid SIK.
+The API contains the following endpoints: 
+
+- [**Chain**](chain): The Vocdoni blockchain is named Vochain. It is a Byzantine fault-tolerant network based on Tendermint that executes the Vocdoni Protocol logic represented as a state machine. Its main purpose is to register votes to a decentralized data store that is able to guarantee univeral verifiability. The chain endpoints allow you to consult the state of the chain, estimate transactions costs, list organizations, and get more Vochain info.
+- [**Accounts**](accounts): Identified by an Ethereum-like address. An account can create and manage elections, transfer tokens, give power to other accounts on its behalf (delegation) and manage its metadata. This endpoint allows users to set the metadata associated with an existing account and to query for information related to existing accounts.
+- [**Elections**](elections): The elections endpoint serves information related to elections such as basic election information, election keys, and submitted votes, as well as enabling users to create a new election and modify existing ones. There is a set of [options, specifications, and lifecycle states](https://developer.vocdoni.io/protocol#elections) that determine the behavior of an election and how votes are counted. 
+- [**Censuses**](censuses): The census is a key component of any voting process. It specifies the set of users (each identified by a public key or address) eligible to participate in an election. The various types of census are documented [here](https://developer.vocdoni.io/protocol/census). This endpoint provides census information like the Merkle root, type, total weight, and size of a census. It also allows you to import/export censuses and create new ones.
+- [**Votes**](votes): This endpoint serves all the information associated with any specific vote, including its validity. It is also how users can cast votes.
+- [**Wallet**](wallet): The wallet endpoint facilitates the creation of accounts on the Vochain. This endpoint fulfills requests relating to the token balance held by a given account. 
+- [**SIK**](sik): The Secret Identity Key is a user-generated piece of information that proves the user's identity without revealing it. It is the hash of the user's address, the signature of a public message, and an optional secret part. It is used to ensure anonymous voting. All registered accounts or anonymous voters must register a SIK, and these keys are all stored in a Merkle tree. The `/siks` endpoints helps to generate a proof of membership, get the current valid SIK roots, or check if an account has a valid SIK.
 
 
 ### Errors 

api/docs/descriptions/censusAddHandler.md

@@ -1,15 +1,15 @@
-Add list of public key/address with its weight to an unpublished census and returns the resulting 
+Adds list of public keys/addresses and voting weights to an unpublished census. Returns the resulting 
 [Merkle Root](https://en.wikipedia.org/wiki/Merkle_tree).  
 
 Each addition will modify the census merkle root creating a new "snapshot" of the census at this moment. This root  identifies the census at this point and can be used to publish the census at this specific state.
 
-For example, supposing a census with id `0x1234` (random hex string generated during census creation), add 10 keys will generate specific root for this state, ex `0xabcd`. 
+For example, supposing a census with id `0x1234` (random hex string generated during census creation), adding 10 keys will generate specific root for this state, ex `0xabcd`. 
 
-If we add 5 keys more, the resulting root changes, the keys are added and the new census have the first 10 keys plus the last 5, with a resulting root of `0xffff`. 
+If we add 5 keys more, the resulting root changes, the keys are added, and the new census has the first 10 keys plus the 5 new ones, with a resulting root of `0xffff`. 
 
-So, at [publishing moment](census-publish), you could specify no root to publish census on the last 
-state (`0xffff`), which will publish the first 10 plus the last 5. Or either specify the snapshot point which you want to publish the census, for example `0x1234`, which will publish just the first 10th.
+So, when [publishing](census-publish) the census, you could specify 'no root' to publish census on the last 
+state (`0xffff`), which will publish a census of all 15 voters. Or you could specify the snapshot point at which you want to publish, for example `0x1234`, which will publish a census containing just the first 10 voters.
 
 - Requires Bearer token 
-- Adds a list of wallet public key or wallet address to a census with a specific weight
+- Adds a list of wallet public key or wallet addresses to a census with a specific weight
 - If the weight parameter is missing, weight=1 is considered

api/docs/descriptions/censusCreateHandler.md

@@ -1,10 +1,10 @@
-Create a new census on the backend side. The census is still unpublished until [publish](publish-census) is called.  
+Creates a new census on the backend side. The census is still unpublished until [publish](publish-census) is called.  
 
-To create the census it require a `Bearer token` created on the user side using a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). This token **should we stored for the user to perform operations to this census** such add participants or publish.
+To create the census a `Bearer token` is required. This is created on the user side using a [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier). This token **should we stored for the user to perform operations to this census** such adding participants or publishing the census.
 
-It return a new random censusID (a random 32 bytes hex string), which are used (along with the Bearer token) to [add participant keys](add-participants-to-census) to the census. Once the census is published no more keys can be added.
+Returns a new random censusID (a random 32 byte hex string), which is used (along with the Bearer token) to [add participant keys](add-participants-to-census) to the census. Once the census is published no more keys can be added.
 
-To use a census on an election, it **must be published**.
+To use a census for an election, it **must be published**.
 
 - Available types are: `weighted` and `zkindexed`
-- Require header Bearer token created user side
+- Requires header Bearer token created user side

api/docs/descriptions/censusProofHandler.md

@@ -1,6 +1,6 @@
-Prove the key and weight belong to the census root hash.
+Proves that the key and weight belong to the census root hash.
 
-If the key exists on the census returns Merkle root information. `Proof` property is referred to the siblings of Merkle tree, the `value` points to the leaf of the Merkle Tree for this key (on this case, the weight), and weight is just the key weight for this census. 
+If the key exists on the census, returns Merkle root information. The `Proof` property refers to the key's siblings on the Merkle tree, the `value` points to the leaf of the Merkle Tree for this key (in this case, the weight), and weight is just the key's weight for this census. 
 
 [Further reading](/protocol/Census/off-chain-tree)
 

api/docs/descriptions/censusPublishCheckHandler.md

@@ -1,3 +1,3 @@
-Returns the publish status of a specific census by its ID, including the IPFS URI where it's uploaded, if available. This handler checks whether a census has been published successfully and retrieves its access URI or any errors that occurred during the publication process.
+Returns the publication status of a specific census by its ID, including the IPFS URI where it's uploaded, if available. This handler checks whether a census has been published successfully and retrieves its access URI or any errors that occurred during the publication process.
 
 This endpoint can be useful for anyone looking to verify the publication status of a census, and it facilitates accessing the published data directly through the returned URI.

api/docs/descriptions/censusPublishHandler.md

@@ -1,6 +1,6 @@
-Register a census to the storage (IPFS in our case). After this, the census can't be edited. 
+Registers a census to storage (IPFS in our case). After this, the census can't be edited. 
 
-You could provide the census Merkle root to specify census publication at specific snapshot. See [censuses/{censusId}/participants](census-add-participants-to-census)
+You can optionally provide the census Merkle root to specify census publication at a specific snapshot. See [censuses/{censusId}/participants](census-add-participants-to-census)
 
 - Requires Bearer token
 - The census is copied to a new census identified by its Merkle Root

api/docs/descriptions/chainInfoHandler.md

@@ -1,15 +1,12 @@
-Return basic Vocdoni Blockchain (Vochain) information like blockTime, chainId, current height...
+Returns basic Vocdoni Blockchain (Vochain) information like blockTime, chainId, current height, and more.
 
 `blockTime`: each array position return average time for 1 minute, 10 minutes, 1 hour, 6 hours and 24 hours.
 
 `blockTime`: every array position represents the average for 1 minute, 10m, 1h, 6h, 24h
 
-`MaxCensusSize`: is a new feature introduced in the blockchain that is used to limit the number of  votes that can be registered for an election. This feature helps to prevent any potential overflow of the blockchain when the number of votes goes beyond the maximum limit. This is the maximum value  that an election creation can allow.
+`MaxCensusSize`: is used to limit the number of voters that can be registered to a given census. This feature helps to prevent any potential overflow of the blockchain when the number of votes goes beyond the maximum limit. This is the maximum value that an election creation can allow.
 
-In order to create an election, the creator is required to set the `MaxCensusSize` parameter to a proper value. Typically, this value should be equal to the size of the census. If the MaxCensusSize parameter is set to 0, an error will occur and the election cannot be created.
+In order to create an election, the creator is required to set the `MaxCensusSize` parameter to a proper value. Typically, this value should be equal to the size of the census. If the MaxCensusSize parameter is set to 0, an error will occur and the election cannot be created. If the `MaxCensusSize` is greater than allowed by the blockchain, an error will be returned.
 
-The `MaxCensusSize` parameter determines the maximum number of votes that can be registered by the blockchain.  If the number of votes exceeds this limit, the vote transaction will fail (overwrite votes does not count).
 
-See `MaxCensusSize` attribute on the VocdoniSDK  to add the maximum census size to a single election. Will throw an error if is superior than the allowed on the Vochain: `Max census size for the election is greater than allowed size`.
-
-`networkCapacity`  indicates how many votes per block is the blockchain supposed to achieve. As bigger the capacity as cheaper the elections.
+`networkCapacity`  indicates how many votes per block is the blockchain expected to achieve. Larger capacity translates to cheaper elections.