Updating the Bitcoin Price Feed Tutorial Documentation

docs/index.md → docs/Ecosystem.md

@@ -4,17 +4,17 @@
 
 The Witnet protocol enables a network of computers to act as a
 **decentralized oracle** that retrieves, attests and delivers
-information in behalf of **smart contracts** in a **tamper-resistant**
+information on behalf of **smart contracts** in a **tamper-resistant**
 way.
 
 > This _Decentralized Oracle Network (DON)_ maintains and distributes a
-> _block chain_ data structure that serves as a common ledger for the
+> _blockchain_ data structure that serves as a common ledger for the
 > operation of the protocol as well as for the _wit_ token, which is
-> central for incentivizing the network players to abide by the protocol
+> crucial for incentivizing the network players to abide by the protocol
 > and make them liable for any misbehavior. —
 > [Witnet Whitepaper][whitepaper]
 
-Active network participants **earn wit tokens** for fulfilling the data
+Active network participants **earn WIT tokens** for fulfilling the data
 retrieval, attestation and delivery tasks coming from different smart
 contract platforms such as [Ethereum][ethereum].
 
@@ -31,8 +31,8 @@ contracts.
 
 ## Developers
 
-The Witnet ecosystem welcomes developers of all kind of backgrounds:
-from people who contribute to [Witnet-Rust] or [Sheikah] to those who
+The Witnet ecosystem welcomes developers with all types of background:
+from people who contribute to [Witnet-Rust], [Sheikah] or any of the community [Operator Tools] to those who
 want to
 [connect their Ethereum smart contracts to external APIs][ethereum].
 Developers can:
@@ -44,20 +44,18 @@ Developers can:
 
 ## Witnet Foundation
 
-[Witnet Foundation][foundation] is the independent entity currently in
-charge of funding the development of Witnet-Rust and Sheikah, as well
-as fostering the thriving ecosystem around the Witnet protocol.
+The Witnet Foundation is an independent entity, designated to fund the development of Witnet-Rust and Sheikah and foster a thriving and engaged ecosystem around the Witnet protocol.
 
-## Other stakeholders
+## Other contributions
 The Witnet community is open to everyone. Even if you are not a
 developer or node operator, there are
-[many things you can do][contributing] to spread the word!
+[many things you can do][contributing] to contribute to the ecosystem!
 
 [apis-illustration]: assets/images/APIs.svg
 [ethereum]: try/use-from-ethereum
-[foundation]: https://witnet.foundation
-[whitepaper]: https://witnet.io/static/witnet-whitepaper.pdf
+[whitepaper]: https://witnet.io/witnet-whitepaper.pdf
 [run-a-node]: /try/run-a-node
 [contributing]: /developer/contributing
 [Witnet-Rust]: https://github.com/witnet/witnet-rust
 [Sheikah]: https://github.com/witnet/sheikah
+[Operator Tools]: https://github.com/witnet/witnet-operator-tools

docs/tutorials/bitcoin-price-feed/create-project.md → docs/tutorials/bitcoin-price-feed/1-create-project.md

@@ -18,8 +18,7 @@ truffle unbox witnet/truffle-box
 ```
 
 You can keep reading this page to learn more about the Truffle box
-boilerplate, but if you are feeling impatient you can [jump into the
-next step][next].
+boilerplate, but if you are feeling impatient you can [jump straight to defining data sources][next].
 
 ### Project folder structure
 
@@ -49,4 +48,4 @@ You are now ready to move forward into
 [discord]: https://discord.gg/X4uurfP
 [truffle]: https://www.trufflesuite.com/
 [intro]: /tutorials/bitcoin-price-feed/introduction
-[next]: /tutorials/bitcoin-price-feed/sources
+[next]: /tutorials/bitcoin-price-feed/2-sources

docs/tutorials/bitcoin-price-feed/sources.md → docs/tutorials/bitcoin-price-feed/2-sources.md

@@ -8,40 +8,40 @@
 ## A quick intro on Witnet data sources
 
 **Data sources are each of the endpoints from which you want Witnet to
-retrieve the data**. Most times, these will be the URLs of public APIs.
+retrieve the data**. Most of the time, these will be the URLs of public APIs.
 
 There is no limit to the number of sources in a single Witnet
-request—although the more sources, the higher the fees will be.
+request - although the more sources, the higher the fees will be.
 
-**Each source can have a companion script** that lists operations that
+**Each source can have a companion script** that lists the operations
 we want the witnesses to apply on the retrieved data. This enables you
 to get the information of your interest extracted out of larger data
 structures like JSON objects.
 
 ## Choose your sources carefully
 
 Just like your friends—and your enemies—your **data sources need to be
-chosen wisely**. The *[Garbage In, Garbage Out][GIGO]* principle really
+chosen wisely**. The *[Garbage In, Garbage Out][GIGO]* principle
 applies here. Regardless of the many *checks-and-balances*,
 well-designed incentives and security measures that the Witnet protocol
 implements, if the data sources in your Witnet requests are not
-reliable, either will your contracts be.
+reliable, your contracts won't be either.
 
-The more data sources and the more reliable they are, the more
-trust-mitigated your Witnet requests will become. That is, your
+The more **reliable** data sources you list, the more
+trust-mitigated your Witnet requests will become. In other words, your
 contracts will be more resilient to downtime, failure or corruption of
 each separate source.
 
 ## Introducing smart data sources
 
-The scripting language used in Witnet requests is quite rich indeed: in
+The scripting language used in Witnet requests is very flexible: in
 addition to selecting specific pieces of data, you can also transform
-those so they are uniform and can be compared or aggregated together.
-E.g. imagine a request that queries weather data. One source may use
-Celsius and the other may use Fahrenheit, but you will tell Witnet to
-transform one into another so they can be averaged.
+them so they are uniform and can be compared or aggregated together.
+For example, imagine a request that queries weather data. One source may use
+Celsius and the other may use Fahrenheit. You can tell Witnet to
+transform them both to Celcius so they can be averaged.
 
-In this tutorial, you will be defining two data sources—one for querying
+In this tutorial, you will be defining two data sources — one querying
 [Bitstamp] and the other for [CoinDesk]:
 
 ```javascript tab="Source 1: Bitstamp"
@@ -53,27 +53,26 @@ const bitstamp = new Witnet.Source("https://www.bitstamp.net/api/ticker/")
 
 ```javascript tab="Source 2: CoinDesk"
 // Retrieves USD price of a bitcoin from CoinDesk's "bitcoin price index" API
-// The JSON here is a bit more complex, thus more operators are needed
+// The JSON here is a bit more complex, so more operators are needed
 const coindesk = new Witnet.Source("https://api.coindesk.com/v1/bpi/currentprice.json")
   .parseMapJSON()         // Parse a `Map` from the retrieved `String`
   .getMap("bpi")          // Get the `Map` value associated to the `bpi` key
   .getMap("USD")          // Get the `Map` value associated to the `USD` key
   .getFloat("rate_float") // Get the `Float` value associated to the `rate_float` key
 ```
 
-These scripts are quite self-explanatory, but there are a few details
-that are worth noticing:
+A few things worth noticing:
 
 - The operators and data types that can be used are defined by the
   [RADON domain-specific language][radon].
 - Each operator is applied on the output of the previous operator, just
   as you would expect from Javascript method chaining or
   [the builder pattern][builder].
 - Source scripts always start with a `String`[^1].
-- Key-value data structures (roughly alike to Javascript *objects*,
+- Key-value data structures (roughly similar to Javascript *objects*,
   Python *dictionaries* or Solidity *mappings*) are called *maps*.
 - Values in maps cannot be accessed directly by name as `.keyName` but
-  rather accessed through a call to one of the `.getArray("keyName")`,
+  instead through a call to one of the `.getArray("keyName")`,
   `.getBoolean("keyName")`, `.getInteger("keyName")`, `.getFloat("keyName")`,
   `.getInteger("keyName")`, `.getMap("keyName")` or `.getString("keyName")` operators.
 - The final return type of a script is that of its last operator.
@@ -104,7 +103,7 @@ const coindesk = new Witnet.Source("https://api.coindesk.com/v1/bpi/currentprice
   .getFloat("rate_float") // Get the `Float` value associated to the `rate_float` key
 ```
 
-Notice the `import` instruction on top, which makes possible using all
+Notice the `import` instruction at the top, which makes it possible to use all
 the tools that the Witnet Javascript library provides:
 
 ```javascript
@@ -126,7 +125,7 @@ You are done with the sources for now. Let's move forward into
 
 [discord]: https://discord.gg/X4uurfP
 [intro]: /tutorials/bitcoin-price-feed/introduction
-[next]: /tutorials/bitcoin-price-feed/aggregations
+[next]: /tutorials/bitcoin-price-feed/3-aggregations
 [radon]: /protocol/data-requests/overview/#rad-object-notation-radon
 [builder]: https://en.wikipedia.org/wiki/Builder_pattern
 [GIGO]: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out
@@ -135,12 +134,12 @@ You are done with the sources for now. Let's move forward into
 
 [^1]: In future versions, the Witnet protocol will make no assumptions
 on what the data type of the server response will be for different data
-sources. This will allow dealing with formats other than plain text,
-such as multimedia files and any other kind of binaries. Therefore,
-source scripts will start with `Bytes` as the input type and it will be
+sources. This will allow for formats other than plain text,
+such as multimedia files and any kind of binaries. Therefore,
+source scripts will start with `Bytes` as the input type; it will be
 totally up to the requester to specify whether those bytes should be
-interpreted as a `String`, `Integer` or whatnot.
+interpreted as a `String`, `Integer` etc.
 
-[^2]: One of the key features in the future RADON 2.0 version will be
-implicit type casting, which will dramatically cut off the size of
+[^2]: One of the key features in RADON 2.0 will be
+implicit type casting, which will dramatically reduce the size of
 scripts.

docs/tutorials/bitcoin-price-feed/aggregations.md → docs/tutorials/bitcoin-price-feed/3-aggregations.md

@@ -8,7 +8,7 @@
 ## What is an aggregator?
 
 Aggregators define how to reduce or merge the result of multiple sources
-into a single data point. They are similar to Javascript's `.reduce()`
+into a single data point. They are similar to JavaScript's `.reduce()`
 method or the [`fold` higher-order function][fold] from many programming
 languages.
 
@@ -22,7 +22,7 @@ outliers by using one or more statistical primitives.
 - When a Witnet node gets a request assigned for resolution, it
   retrieves every source, applies the source companion scripts on the
   retrieved data, collects the results into an `Array`, and then apply
-  the aggregator on it, first running the filters and eventually the
+  the aggregator on it, first running the filters and later the
   reducer.
 
 
@@ -57,8 +57,8 @@ function.
 
 ## Tally by average
 
-For this tutorial, you will be using a tally function that is quite
-equivalent to the aggregation function:
+For this tutorial, we will be using a tally function that is quite
+similar to the aggregation function:
 
 ```javascript
 // Filters out any value that is more than 1.5 times the standard
@@ -72,8 +72,8 @@ const tally = new Witnet.Tally({
 })
 ```
 
-Note however that in this case the deviation filter is using a narrower
-threshold (`1.0` instead of `1.5`). This is to make sure that malicious
+Note, however, that in this case the deviation filter is using a narrower
+threshold (`1.0` instead of `1.5`). This is to ensure that malicious
 data points will not affect the final result, and that the witnesses
 that produced such outliers will be punished for their misbehavior.
 
@@ -130,4 +130,4 @@ Now it is time to put everything together and
 [discord]: https://discord.gg/X4uurfP
 [intro]: /tutorials/bitcoin-price-feed/introduction
 [fold]: https://en.wikipedia.org/wiki/Fold_(higher-order_function)
-[next]: /tutorials/bitcoin-price-feed/fine-tuning
+[next]: /tutorials/bitcoin-price-feed/4-fine-tuning

docs/tutorials/bitcoin-price-feed/fine-tuning.md → docs/tutorials/bitcoin-price-feed/4-fine-tuning.md

@@ -50,10 +50,10 @@ The `witnesses` is the minimum number of Witnet nodes that will be
 resolving each specific request.
 
 In general, the higher the number of witnesses, the safer the request.
-However, fees should be proportional to this number.
+However, a higher number of witnesses generally means higher fees.
 
 The actual number of nodes that will resolve each request is guaranteed
-to be equal than the specified number. If for some reason the
+to be equal to the specified number. If for some reason the
 network fails to assign the request to enough nodes, it will be
 reassigned in every subsequent epoch to a different randomly-selected
 set of nodes until the required number is reached.
@@ -62,11 +62,11 @@ The `backup_witnesses` is the number of Witnet nodes that will be used
 as a backup in case some of the originally assigned nodes fail to
 fulfill their commitments.
 
-A higher `backup_witnesses` number implies more fees but also guarantees
-that the request will be timely resolved. In the other hand, if you use
-small `backup_witnesses` values, the risk is that your request will need
+A higher `backup_witnesses` value corresponds with higher fees but also guarantees
+that the request will be resolved in a timely fashion. On the other hand,
+a small `backup_witnesses` value comes with the risk that your request will need
 to be retried many times and therefore the result may be potentially
-inaccurate (in case the queried data point changes very fast).
+inaccurate (especially if the queried data point changes rapidly).
 
 #### Optional arguments for `.setQuorum`
 
@@ -82,32 +82,32 @@ The `.setQuorum` method accepts three more optional arguments:
 )
 ```  
 
-The `extra_commit_rounds` number is how many extra epochs will Witnet
-nodes be given for commiting their partial results. A number of rounds
+The `extra_commit_rounds` number specifies how many extra epochs Witnet
+nodes will be given for committing their partial results. A number
 greater than `0` strengthens the chances of a Witnet request being
 resolved to a value instead of timing out. This parameter is actually an
-upper threshold, i.e. the request will progress into reveal stage as
+upper threshold, i.e. the request will progress into a reveal stage as
 soon as the number of commitments equals the number of required witnesses.
 If not set, this parameter defaults to `1`. This parameter has no impact
 on the price of the request.
 
-The `extra_reveal_rounds` number is how many extra epochs will Witnet
-nodes be given for revealing their partial results. A number of rounds
+The `extra_reveal_rounds` number specifies how many extra epochs Witnet
+nodes will be given to reveal their partial results. A number
 greater than `0` strengthens the security of a Witnet request by
 preventing miners from withholding reveal transactions—as the subsequent
 miners can include any reveal transactions withheld by a former miner.
-This parameter is actually an upper threshold, i.e. the request will get
+This parameter is actually an upper threshold, i.e. the request will be
 tallied and finalized as soon as the number of reveals equals the number
 of commitments. If not set, this parameter defaults to `1`. This
 parameter has no impact on the price of the request.
 
-The `minimum_consensus` percentage allows to define a threshold for
+The `minimum_consensus` percentage allows users to define a threshold for
 aborting resolution of a request if the witnessing nodes did not arrive
-to broad consensus. That is, aggregator and tally functions will not be
+at broad consensus. That is, aggregator and tally functions will not be
 applied if the ratio of valid values vs. errors is below this threshold.
-*E.g. a `minimum_consensus` threshold of `70` requires a `70%` of the
-witnesses to report a valid value, otherwise the result of the request
-will be an error stating "insufficient consensus"*. If not set, this
+*E.g. a `minimum_consensus` threshold of `70` requires `70%` of the
+witnesses to report a valid value, otherwise the request
+will result in an error, stating "insufficient consensus"*. If not set, this
 parameter defaults to `51`.
 
 ### Set the fees
@@ -116,7 +116,7 @@ parameter defaults to `51`.
 ```
 
 Witnet allows parametrization of many of the economic incentives that
-affect the life cycle of your requests. Namely, those incentives are:
+affect the life cycle of your requests. These incentives include:
 
 - `request_fee`: the amount of wit tokens that will be earned by the
   Witnet miner that publishes your request in a block.
@@ -129,8 +129,8 @@ affect the life cycle of your requests. Namely, those incentives are:
 - `reveal_fee`: the amount of wit tokens that will be earned by Witnet
   miners for each valid reveal transaction they include in a block.
 - `tally_fee`: the amount of wit tokens that will be earned by the
-  Witnet miner that publishes in a block the tally of all the reveal
-  transactions related to your request.
+  Witnet miner that publishes the tally of all the reveal
+  transactions related to your request in a block.
 
 !!! question "How can I compute the total cost of a request?"
     The total cost of a Witnet request equals:
@@ -152,7 +152,7 @@ affect the life cycle of your requests. Namely, those incentives are:
 .schedule(timestamp)
 ```
 
-Witnet requests can be scheduled for resolution in a particular date and
+Witnet requests can be scheduled for resolution on a particular date and
 time in the future.
 
 Timestamps need to be provided as [POSIX timestamps][POSIX], i.e.
@@ -224,4 +224,4 @@ Time to go ahead and [compile the request][next].
 [discord]: https://discord.gg/X4uurfP
 [intro]: /tutorials/bitcoin-price-feed/introduction
 [POSIX]: https://en.wikipedia.org/wiki/Unix_time
-[next]: /tutorials/bitcoin-price-feed/compiling
+[next]: /tutorials/bitcoin-price-feed/5-compiling

docs/tutorials/bitcoin-price-feed/compiling.md → docs/tutorials/bitcoin-price-feed/5-compiling.md

@@ -22,10 +22,10 @@ The `compile-requests` npm task will:
 3. Try to compile the requests into Witnet bytecode.
 4. Put the bytecode into auxiliary Solidity contracts that you can
    import into your own contracts.
-5. Write [migration files][migrations] with default constructor
+5. Write [migration files][deploy] with default constructor
    arguments that you can later customize.
 
-If you go and look at the `contracts/requests` folder, you will notice a
+If you now take a look in the `contracts/requests` folder, you will notice a
 new file called `BitcoinPrice.sol`. It will contain something like this:
 
 ```solidity
@@ -40,11 +40,10 @@ contract BitcoinPriceRequest is Request {
 ```
 
 As you can see, the contract contains the byte code for the request you
-just wrote, exported as a Solidity contract that you can in turn import
+just wrote, exported as a Solidity contract that you can then import
 and instantiate from your own contracts.
 
-Now the next step is pretty straightforward:
-[write your main consumer contract][next].
+The next step is to [write your main consumer contract][next].
 
 !!! question "Remember: You are not alone!"
     You are invited to join the [Witnet Community Discord][discord].
@@ -53,6 +52,6 @@ Now the next step is pretty straightforward:
     tutorial.
 
 [discord]: https://discord.gg/X4uurfP
-[migrations]: /tutorials/bitcoin-price-feed/migrations
+[deploy]: /tutorials/bitcoin-price-feed/7-deploy
 [intro]: /tutorials/bitcoin-price-feed/introduction
-[next]: /tutorials/bitcoin-price-feed/contract
+[next]: /tutorials/bitcoin-price-feed/6-contract