Update in paragraphs, flow of text and explanations

_src/_guides/tutorial-car-telemetry-app.md

@@ -1,16 +1,25 @@
 ---
 layout: guide
 
-title: "Tutorial: Car Telemetry App"
-tagline: Learn how to build telemetry apps to track specific dynamic parameters of an asset.
+title: "Tutorial: How to create a digital twin of your car"
+tagline: Learn how to build a telemetry app to track specific dynamic parameters of an asset, such as the mileage of a car.
 header: header-car.jpg
 learn: >
-    - How BigchainDB can be used to build telemetry apps to track specific dynamic parameters of an asset.
+    - How BigchainDB can be used to build telemetry apps to track specific dynamic parameters of an asset
+    
+    - How assets can be used to represent real objects on BigchainDB
 
-    - How to make a `CREATE` transaction to create a car. Assets as representation of real objects.
-
-    - How asset metadata is updated. In BigchainDB it is possible to use `TRANSFER` transactions to change the state of an asset, in this case the mileage of a car.
+    - How to make a `CREATE` transaction to digitally register an object on BigchainDB
+    
+    - How asset metadata is updated by using `TRANSFER` transactions to change the state of an asset (the mileage of a car in our example)
 ---
+Hi there! Welcome to our first tutorial! For this tutorial, we assume that you are familiar with the BigchainDB primitives (assets, inputs, outputs, transactions etc.). If you are not, familiarize yourself here (insert link of key concepts). 
+
+# About digital twins
+
+We are moving towards an era, where the internet of things is becoming real. Cars become more connected, devices equipped with sensors can communicate their data and objects become smarter and smarter. This triggers the need for a digital representation of these devices to store their data in a safe location and to have a complete audit trail of their activity. This is the core idea of the digital twin of an object. BigchainDB is an ideal solution to create digital twins of smart devices. In this tutorial, you will learn how to build a simple and basic version of a digital twin of your car, which allows its owner to store and update the mileage of the car.  
+
+Let's get started!
 
 # Setup
 
@@ -20,7 +29,7 @@ Start by installing the official [BigchainDB JavaScript driver](https://github.c
 npm i bigchaindb-driver
 ```
 
-Then include as a module and connect to IPDB or any BigchainDB node:
+Then, include that as a module and connect to IPDB or any BigchainDB node. Use the credentials below or create your own app_id and app_key (learn here how to do that: https://ipdb.io/#getstarted). 
 
 ```js
 const BigchainDB = require('bigchaindb-driver')
@@ -32,21 +41,21 @@ const conn = new BigchainDB.Connection(API_PATH, {
 })
 ```
 
-# Create a key pair for Alice
+# Create a key pair 
 
-Alice will be the owner of the car, and she will be the only one able to create the asset and update the mileage field.
+In BigchainDB, users are represented as a private and public key pair. In our case, a key pair for Alice will be created. Alice will be the owner of the car, and she will be the only one able to create this specific asset and update the mileage of the car. 
 
-We can generate a keypair from a seed phrase, so we will just need to remember this seed phrase.
+You can generate a key pair from a seed phrase, so you will just need to remember this particular seed phrase. The code below illustrates that.
 
 ```js
 const alice = new BigchainDB.Ed25519Keypair(bip39.mnemonicToSeed('seedPhrase').slice(0,32))
 ```
 
-# Create and post the asset
+# Digital registration of an asset on BigchainDB
 
-An asset in our case will represent an object in the real life. But it can represent a claim, a token, a version document, a finite state machine, etc. The asset will live in BigchainDB forever and there is no possibility to delete it.
+After having generated a key pair, you now need to register your car in BigchainDB. This corresponds to an asset registration. In our case, an asset will represent an object in real life, namely a car. This asset will live inside BigchainDB forever and there is no possibility to delete it.
 
-First we need to define the asset field that represents the car. It has a JSON format
+First, you need to define the asset field that represents the car. It has a JSON format:
 
 ```js
 const vehicle = {
@@ -59,7 +68,7 @@ const vehicle = {
 }
 ```
 
-To post a transaction in BigchainDB, first we need to create it, then sign it and then send it. There are different methods for each step:
+As a next step, you need to generate a `CREATE´ transaction to link the defined asset to the user alice. To post this transaction in BigchainDB, first you need to create it, then sign it and then send it. There are different methods for each step:
 
 ```js
 function createCar() {
@@ -93,15 +102,19 @@ function createCar() {
 }
 ```
 
-`carOwner.publicKey` can be considered as the Input for the transaction. When you sign a transaction in BigchainDB you have the rights for the next `TRANSFER` transactions that could be done with this asset. You always sign with a private key that is derivative from the seed phrase.
+Now, you have digitally registered the car on BigchainDB, respectively in our case on IPDB. Note that the metadata field is used to record the mileage, which is currently set to 0.
 
 With the `pollStatusAndFetchTransaction` we check the status of the transaction every 0.5 seconds.
 
-Once a transaction ends up in a decided-valid block, that's it. There's no changing it, no deleting it. But you can use `TRANSFER` transactions (with their arbitrary metadata) to store whatever you like, including information that could be interpreted as changing an asset (if that's how you want it to be interpreted).
+Once a transaction ends up in a decided-valid block, it "edged into stone". There's no changing it, no deleting it. The asset is registered now and cannot be deleted. However, the usage of the metadata field allows you to do updates in the asset. For this, you can use `TRANSFER` transactions (with their arbitrary metadata) to store any type of information, including information that could be interpreted as changing an asset (if that's how you want it to be interpreted).
 
-We will use this feature to trace the mileage of the car.
+We will use this feature to update the mileage of the car. Note that by using `carOwner.publicKey` in the output of our create transaction, you have established that Alice will be the only person, who will be able to do an update, respectively a `TRANSFER´ transaction for this asset, since the usage of this output as an input in a separate transaction will require a signature with Alice’s private key. 
 
-Before creating the transfer transaction, we search for the last transaction with the asset id, as we will update this last transaction.
+# Update of an asset on BigchainDB
+
+Since an update of the mileage of a car does not imply any change in the ownership, your transfer transaction will simply be a transfer transaction with the previous owner (Alice) as beneficiary, but with new metadata in the transaction. So, technically, Alice is transferring the car to herself and just adding additional, new information to that transaction. 
+
+Before creating the transfer transaction, you need to search for the last transaction with the asset id, as you will update this specific last transaction:
 
 ```js
 conn.listTransactions(assetId)
@@ -118,18 +131,18 @@ conn.listTransactions(assetId)
                 }
             })
         )
-        // In our case there should be just one input that has not beeen spent with the asseId
+        // In our case there should be just one input that has not beeen spent with the assetId
         return unspents = txList.filter((tx) => inputTransactions.indexOf(tx.id) === -1)
     })
 ```
 
-The `listTransactions` method of BigchainDB retrieves all of the create and transfer transaction with the asset id. Then we check for the inputs that have not been spent. In this tutorial we are just working with one input and one ouput for each transaction, so there should be just one input that has not been spent yet, the one belonging to the last transaction.
+The `listTransactions` method of BigchainDB retrieves all of the create and transfer transactions with a specific asset id. Then, we check for the inputs that have not been spent yet. This indicates us, which was the last transaction. In this tutorial, we are just working with one input and one ouput for each transaction, so there should be just one input that has not been spent yet, namely the one belonging to the last transaction.
 
-We now create the transfer transaction:
+Based on that, we can now create the transfer transaction:
 
 ```js
 function updateMileage(assetId, mileageValue) {
-    // Update the car with a new mileage of 55km. First we query for the asset car that we created
+    // Update the car with a new mileageValue of e.g. 55km. First, we query for the asset car that we created
     conn.listTransactions(assetId)
         .then((txList) => {
             if (txList.length <= 1) {
@@ -143,7 +156,7 @@ function updateMileage(assetId, mileageValue) {
                     }
                 })
             )
-            // In our case there should be just one input not spend with the asseId
+            // In our case there should be just one input not spend with the assetId
             return unspents = txList.filter((tx) => inputTransactions.indexOf(tx.id) === -1)
         })
 
@@ -174,6 +187,11 @@ function updateMileage(assetId, mileageValue) {
 }
 ```
 
-Once we have the last transaction we create the transfer transaction with the new metadata value. We also need an output to preserve the ownership of the car and the index of the input being spent. In this case that's Alice and the input being spent is 0, as there is just one input. Then we sign the transaction and we send it to BigchainDB.
+Once you have the last transaction, you create the transfer transaction with the new metadata value of e.g. 55 km. 
+Note again that in the output of this transfer transaction we have `carOwner.publicKey´. This shows that Alice is not transferring the ownership of the car to anybody else, because she is still the only person who can use that output as an input in another transaction. Furthermore, the input being spent is 0, as there is just one input. 
+So, finally you sign the transaction and send it to BigchainDB. You have now updated your asset and it is now recorded that your car has driven a distance of 55 km.
+
+That's it, we have created a car asset, and every time the car travels new kilometers the `updateMileage` will be called with the new value of it, which leads to a continuous update in the car mileage. 
+
+Congratulations! You have successfully finished your first BigchainDB tutorial. 
 
-That's it, we have created a car asset, and every time the car travels new kilometers the `updateMileage` should be called with the new value of it.