docs: update docs

src/getting-started/car-server.md

@@ -2,7 +2,7 @@
 
 It is an HTTP server that converts arbitrary content into a [CARv2](https://ipld.io/specs/transport/car/carv2/) file and serves it over HTTP - supporting the latest CARv2 format,
 which is not yet entirely supported by other crates in the Rust ecosystem.
-Following the following steps, you can run the server locally and upload and download files.
+The next steps describe how to run the server locally and use it to upload and download files.
 
 <div class="warning">
 The server is a proof of concept, showcasing our CARv2 implementation, but it is not intended to be used in production.
@@ -37,9 +37,9 @@ Follow these steps to ensure your setup works as expected:
 
 1. Upload a test file using the instructions in the [Upload a file](../storage-provider-cli/storage.md#upload-a-file) section. Make sure to note the CID returned by the server.
 
-2. Download the CAR file using the CID you received, following the steps in the [Download the CAR File](../storage-provider-cli/storage.md#download-the-car-file) section.
+2. Download the CAR file using the retrieved CID, following the steps in the [Download the CAR File](../storage-provider-cli/storage.md#download-the-car-file) section.
 
-3. [Optional] Verify the contents of the downloaded CAR file. You can use [go-car](https://github.com/ipld/go-car/tree/master/cmd/car#install)'s `inspect` command. Like so.
+3. [Optional] Verify the contents of the downloaded CAR file. Using, for example, [go-car](https://github.com/ipld/go-car/tree/master/cmd/car#install)'s `inspect` command:
 
    ```bash
    car inspect <target_file>
@@ -57,4 +57,4 @@ Follow these steps to ensure your setup works as expected:
    car extract <target_file>
    ```
 
-If you can successfully upload a file, receive a CID, download the corresponding CAR file, and verify its contents, your CAR server setup is working correctly.
+If a file can be successfully uploaded, the server produces a CID, allows download the corresponding CAR file, and verify its contents, the CAR server setup is working correctly.

src/getting-started/demo.md

@@ -1,8 +1,7 @@
 # Real-world use case demo
 
 <div class="warning">
-Before reading this guide,
-please ensure you've followed the <a href="./local-testnet.md">local testnet</a> guide and that a working testnet is running!
+Before reading this guide, please follow the <a href="./local-testnet.md">local testnet</a> guide and have a working testnet running!
 </div>
 
 A high-level overview with diagrams of the process described below can be found in <a href="../pallets/index.md">Pallets section</a>.
@@ -123,7 +122,7 @@ $ storagext-cli --sr25519-key "//Charlie" storage-provider prove-commit "@prove-
 
 <img src="../images/demo/proven.PNG">
 
-[^slash]: You can wait for 5 minutes and observe a `DealSlashed` [Event](../pallets/market.md#events) being published.
+[^slash]: Wait for 5 minutes and observe a `DealSlashed` [Event](../pallets/market.md#events) being published.
 
 ## 3. Proofs and faults
 

src/getting-started/index.md

@@ -1,10 +1,10 @@
 # Getting Started
 
-This chapter will guide you through setting up, running, and trying out the components that have been implemented so far.
+This chapter goes through the process of setting up, running, and trying out the components implemented so far.
 
 ## System Requirements
 
-Before proceeding with the setup, please ensure your system meets the following requirements:
+Before proceeding with the setup, please ensure the host system meets the following requirements:
 
 - **OS**: Linux x86_64/MacOS ARM x64
 - **RAM**: Minimum 8GB, recommended 16GB or more

src/getting-started/local-testnet.md

@@ -1,14 +1,14 @@
 # Local Testnet - Polka Storage Parachain
 
-This guide will help you set up a local parachain network using zombienet.
+This guide helps to set up a local parachain network using zombienet.
 At the end, we will have three nodes: Alice, Bob and Charlie.
 Alice and Bob will be running Polkadot relay chain nodes as validators,
 and Charlie will run a relay chain and parachain node.
 Charlie will be our contact point to the parachain network.
 
 ## Native Binaries
 
-You can download our latest releases's binaries directly and run them on your machine without additional dependencies.
+Our latest releases's binaries are available to download and can be run without additional dependencies.
 We support `Linux x86_64` and `MacOS ARM x64`. The commands below will download:
 
 - [Relay Chain](https://github.com/paritytech/polkadot-sdk/releases) binaries (`polkadot`, `polkadot-prepare-worker`, `polkadot-execute-worker`),
@@ -81,18 +81,16 @@ wget https://s3.eu-central-1.amazonaws.com/polka-storage/polka-storage-testnet.t
 zombienet -p native spawn polka-storage-testnet.toml
 ```
 
-You can easily access the parachain using the Polkadot.js Apps interface by clicking on this link:
+The parachain is also accessible using the Polkadot.js Apps interface by clicking on this link:
 <https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:42069#/explorer>
 
-Where you should be greeted by a page like this:
-
 <p>
   <a href="https://polkadot.js.org/apps/?rpc=ws://127.0.0.1:42069#/explorer">
     <img src="../images/polkadot_substrate_portal.png" alt="Polkadot/Subtrate Portal">
   </a>
 </p>
 
-Or you can interact with the chain via [`storagext-cli`](../storagext-cli/index.md), for example:
+Or interact with the chain via [`storagext-cli`](../storagext-cli/index.md), for example:
 
 ```bash
 storagext-cli --sr25519-key "//Alice" storage-provider register Alice
@@ -114,17 +112,17 @@ Docker Images were only published on x86_64 platforms! They won't work on Kubern
 
 ### Start up the Kubernetes cluster
 
-Using `minikube`, you can start the cluster with the following command:
+Using `minikube`, start the cluster with the following command:
 
 ```
 minikube start
 ```
 
-You can read more about `minikube` on its [Getting Started](https://minikube.sigs.k8s.io/docs/handbook/controls/) page.
+More information about `minikube` is available on its [Getting Started](https://minikube.sigs.k8s.io/docs/handbook/controls/) page.
 
 ### Running the Parachain
 
-1. Create a `local-kube-testnet.toml` file on your machine with the following content.
+1. Create a `local-kube-testnet.toml` file with the following content:
 
 ```toml
 [settings]
@@ -248,21 +246,21 @@ zombie-01b7920d650c18d3d78f75fd8b0978af   temp-collator                      0/1
 
 ### Accessing the Parachain
 
-You can easily access the parachain using the Polkadot.js Apps interface by clicking on this link:
+The parachain is available through the Polkadot.js Apps interface by clicking on this link:
 
 [https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A42069#/explorer](https://polkadot.js.org/apps/?rpc=ws%3A%2F%2F127.0.0.1%3A42069#/explorer)
 
-This link will automatically connect to Charlie's node running on your local machine at port `42069`. The port is configured in `local-kube-testnet.toml` under `rpc_port` for Charlie's node.
+This link will automatically connect to Charlie's node running on a local machine at port `42069`. The port is configured in `local-kube-testnet.toml` under `rpc_port` for Charlie's node.
 
 ## Zombienet Configuration Breakdown
 
-During the setup, you either download a file in the third step of [Linux](#linux-x86_64)/[MacOS](#macos-arm) — `polka-storage-testnet.toml` —
+During the setup either download a file in the third step of [Linux](#linux-x86_64)/[MacOS](#macos-arm) — `polka-storage-testnet.toml` —
 or copy it from the first step of [Running the parachain](#running-the-parachain).
 
 ### Similarities
 
 The two files share most of the contents, so we'll start by covering their similarities.
-For more details, you should refer to the [`zombienet` documentation](https://paritytech.github.io/zombienet/network-definition-spec.html):
+For more details refer to the [`zombienet` documentation](https://paritytech.github.io/zombienet/network-definition-spec.html):
 
 #### `relaychain`
 

src/glossary.md

@@ -120,7 +120,7 @@ lease, and participants might receive rewards or tokens from the project in retu
 
 A deadline is one of the multiple points during a proving period when proofs for some partitions are due.
 
-For more information on deadlines, you can read the original Filecoin specification:
+For more information on deadlines, read the original Filecoin specification:
 <https://spec.filecoin.io/#section-algorithms.pos.post.design>
 
 ### Extrinsics
@@ -136,7 +136,7 @@ For a sector to stop being considered in proving periods, it needs to be declare
 — indicating the storage provider is aware of the faulty sector and will be working to restore it.
 If a sector is faulty for too long, it will be terminated and the deal will be slashed.
 
-For more information on faults, you can read the original Filecoin specification:
+For more information on faults, read the original Filecoin specification:
 <https://spec.filecoin.io/#section-glossary.fault>
 
 ### Full Node
@@ -165,7 +165,7 @@ Partitions are logical groups[^logical] of sectors to be proven together.
 
 The number of sectors to be proven at once is 2349[^computational_limit], as defined by Filecoin.
 
-For more information on partitions, you can read the original Filecoin specification:
+For more information on partitions, read the original Filecoin specification:
 <https://spec.filecoin.io/#section-algorithms.pos.post.constants--terminology>
 
 [^logical]: They do not reflect the physical storage state, only existing in the context of deadlines and proofs.
@@ -177,7 +177,7 @@ For more information on partitions, you can read the original Filecoin specifica
 From the [Polkadot Wiki][1]:
 
 > The smallest unit for the account balance on Substrate based blockchains (Polkadot, Kusama, etc.) is Planck (a reference to Planck Length, the smallest possible distance in the physical Universe).
-> You can compare DOT's Planck to BTC's Satoshi or ETH's Wei. Polkadot's native token DOT equals to \\(10^{10}\\) Planck and Kusama's native token KSM equals to \\(10^{12}\\) Planck.
+> DOT's Planck is like BTC's [Satoshi](https://en.bitcoin.it/wiki/Satoshi_(unit)) or ETH's [Wei](https://ethereum.org/en/developers/docs/intro-to-ether/#denominations). Polkadot's native token DOT equals to \\(10^{10}\\) Planck and Kusama's native token KSM equals to \\(10^{12}\\) Planck.
 
 
 ### Polkadot
@@ -206,7 +206,7 @@ A proving period is when storage providers' commitments are audited,
 and they must prove they are still storing the data from the deals they signed
 - the average period for proving all sectors maintained by a provider (default set to 24 hours).
 
-For more information on proving periods, you can read the original Filecoin specification:
+For more information on proving periods, read the original Filecoin specification:
 - Proving periods in the context of Window Proof of Spacetime — <https://spec.filecoin.io/#section-algorithms.pos.post.windowpost>
 - Proving periods in the context of Filecoin's system design — <https://spec.filecoin.io/#section-algorithms.pos.post.design>
 
@@ -221,7 +221,7 @@ The sector is the default unit of storage that providers put in the network.
 A sector is a contiguous array of bytes on which a storage provider puts together, seals,and performs Proofs of Spacetime on.
 Storage providers store data on the network in fixed-size sectors.
 
-For more information on sectors, you can read the original Filecoin specification:
+For more information on sectors, read the original Filecoin specification:
 <https://spec.filecoin.io/#section-glossary.sector>
 
 ### Session

src/introduction.md

@@ -31,9 +31,9 @@ The following on-chain logic has been implemented:
 - [Continuously proving](./pallets/storage-provider.md#submit_windowed_post) that the promise of storage has been kept up [PoSt proof](./glossary.md#proofs),
 - [Punishing](./pallets/storage-provider.md#events) for failing to provide storage.
 
-We present a complete real-world scenario [(which you can run on your own!)](./getting-started/demo.md) in which a [Storage Provider](./glossary.md#storage-provider) and a [Storage User](./glossary.md#storage-user) negotiate a deal, perform all the steps necessary to start the storage and then receive rewards (or punishments) for making it happen.
+We present a complete real-world scenario (./getting-started/demo.md) in which a [Storage Provider](./glossary.md#storage-provider) and a [Storage User](./glossary.md#storage-user) negotiate a deal, perform all the steps necessary to start the storage and then receive rewards (or punishments) for making it happen.
 
-You can read more about the project's genesis in:
+More information available about the project's genesis in:
 
 - Treasury Proposal — <https://polkadot.polkassembly.io/post/2107>
 - OpenGov Referendum — <https://polkadot.polkassembly.io/referenda/494>

src/pallets/market.md

@@ -32,15 +32,15 @@ The reserved amount will be considered `free` until it is used in a deal when
 
 #### <a id="add_balance.example" href="#add_balance.example" class="header">Example</a>
 
-Using the `storagext-cli` you can add 1000000000[^existential_deposit] [Plancks](../glossary.md#planck) to Alice's account with the following command[^add_balance]:
+Using the `storagext-cli` to add 1000000000[^existential_deposit] [Plancks](../glossary.md#planck) to Alice's account with the following command[^add_balance]:
 
 ```bash
 storagext-cli --sr25519-key "//Alice" market add-balance 1000000000
 ```
 
 [^existential_deposit]:
     This value is the minimum amount due to Polkadot's existential deposit.
-    You can read more about it at <https://support.polkadot.network/support/solutions/articles/65000168651-what-is-the-existential-deposit->.
+    More information available in: <https://support.polkadot.network/support/solutions/articles/65000168651-what-is-the-existential-deposit->.
 
 [^add_balance]: Read more about the `add-balance` command in [_Storagext CLI/Subcommand `market`/`add-balance`_](../storagext-cli/market.md#add-balance)
 
@@ -57,7 +57,7 @@ lesser than or equal to `free` and greater than 0 (\\({free} \ge {amount} \gt 0\
 
 #### <a id="withdraw_balance.example" href="#withdraw_balance.example" class="header">Example</a>
 
-Using the `storagext-cli` you can withdraw 10000 [Plancks](../glossary.md#planck) from Alice's `free` balance using the following command[^withdraw_balance]:
+Using the `storagext-cli` to withdraw 10000 [Plancks](../glossary.md#planck) from Alice's `free` balance using the following command[^withdraw_balance]:
 
 ```bash
 storagext-cli --sr25519-key "//Alice" market withdraw-balance 10000
@@ -102,7 +102,7 @@ See the [original Filecoin specification](https://spec.filecoin.io/#section-syst
 
 #### <a id="publish_storage_deals.example" href="#publish_storage_deals.example" class="header">Example</a>
 
-Using the `storagext-cli` you can publish deals with `//Alice` as the storage provider and `//Charlie` as the client by running the following command[^publish_storage_deals]:
+Using the `storagext-cli` to publish deals with `//Alice` as the storage provider and `//Charlie` as the client by running the following command[^publish_storage_deals]:
 
 ```bash
 storagext-cli --sr25519-key "//Alice" market publish-storage-deals \
@@ -168,7 +168,7 @@ Non-existing deal IDs will be ignored.
 
 #### <a id="settle_deal_payments.example" href="#settle_deal_payments.example" class="header">Example</a>
 
-Using the `storagext-cli` you can settle deal payments for IDs 97, 1010, 1337 and 42069 using the following command[^settle_deal_payments]:
+Using the `storagext-cli` to settle deal payments for IDs 97, 1010, 1337 and 42069 using the following command[^settle_deal_payments]:
 
 ```bash
 storagext-cli --sr25519-key "//Alice" market settle-deal-payments 97 1010 1337 42069
@@ -222,8 +222,8 @@ The Market Pallet actions can fail with following errors:
   - Deal is not pending.
 - `DealsTooLargeToFitIntoSector` - Sum of all deals piece sizes for a sector exceeds sector size. The sector size is based on the registered proof type. We currently only support registered `StackedDRG2KiBV1P1` proofs, which have 2KiB sector sizes.
 - `TooManyDealsPerBlock` - Tried to activate too many deals at a given `start_block`.
-- `UnexpectedValidationError` - `publish_storage_deals`'s core logic was invoked with a broken invariant that `validate_deals` should call. Report an issue if you receive this error.
-- `DealPreconditionFailed` - Due to a programmer bug. Report an issue if you receive this error.
+- `UnexpectedValidationError` - `publish_storage_deals`'s core logic was invoked with a broken invariant that should be called by `validate_deals`. Please report an issue to the developers.
+- `DealPreconditionFailed` - Due to a programmer bug. Please report an issue to the developers.
 
 ## Constants
 

src/pallets/storage-provider.md

@@ -323,16 +323,16 @@ The Storage Provider Pallet actions can fail with the following errors:
 - `InvalidUnsealedCidForSector` - This error is emitted when the declared unsealed_cid for pre_commit is different from the one calculated by the system.
 - `FaultDeclarationTooLate` - A fault declaration was submitted after the fault declaration cutoff. The fault declaration can be submitted after the upcoming deadline is closed.
 - `FaultRecoveryTooLate` - A fault recovery was submitted after the fault recovery cutoff. The fault recovery can be submitted after the upcoming deadline is closed.
-- `DeadlineError` - An error was encountered in the deadline module. If you encounter this error, please report an issue, as this is a programmer error.
-- `PartitionError` - An error was encountered in the partition module. If you encounter this error, please report an issue, as this is a programmer error.
-- `StorageProviderError` - An error was encountered in the storage provider module. If you encounter this error, please report an issue, as this is a programmer error.
+- `DeadlineError` - An error was encountered in the deadline module. Please report an issue to the developers.
+- `PartitionError` - An error was encountered in the partition module. Please report an issue to the developers.
+- `StorageProviderError` - An error was encountered in the storage provider module. Please report an issue to the developers.
 - `SectorMapError` - An error was encountered in the sector map module. These errors can be:
-  - `FailedToInsertSector` - Internal bounds violation with Sectors. If you encounter this error please report an issue as this is a programmer error.
-  - `FailedToInsertPartition` - Internal bounds violation with partitions. If you encounter this error please report an issue as this is a programmer error.
-- `CouldNotActivateSector` - Failure during prove commit when trying to convert a previously pre-committed sector due to a programming error. Please report an issue if you receive this error.
-- `CouldNotVerifySectorForPreCommit` - Failure during pre-commit due to the [commd](../glossary.md#commitment-of-data) calculation failing due to a programming error. Please report an issue if you receive this error.
-- `SlashingFailed` - Slashing of funds fails due to a programmer error. Please report an issue if you receive this error.
-- `ConversionError` - Due to a programmer error. Please report an issue if you receive this error.
+  - `FailedToInsertSector` - Internal bounds violation with Sectors. Please report an issue to the developers.
+  - `FailedToInsertPartition` - Internal bounds violation with partitions. Please report an issue to the developers.
+- `CouldNotActivateSector` - Failure during prove commit when trying to convert a previously pre-committed sector due to a programming error. Please report an issue to the developers.
+- `CouldNotVerifySectorForPreCommit` - Failure during pre-commit due to the [commd](../glossary.md#commitment-of-data) calculation failing due to a programming error. Please report an issue to the developers.
+- `SlashingFailed` - Slashing of funds fails due to a programmer error. Please report an issue to the developers.
+- `ConversionError` - Due to a programmer error. Please report an issue to the developers.
 
 ## Pallet constants