Implemented changes suggested by Palas in PR review.

marlowe/doc/playground-blockly.adoc

@@ -7,25 +7,25 @@ So far in these tutorials we have concentrated on building contracts in the text
 
 === Getting started
 
-To start building a Blockly project in the Marlowe Playground, which you can find out more about in the section about xref:playground-overview#playground-overview[], select *New Project* and then *Blockly* for the project type. You'll now see a window like this:
+To start building a Blockly project in the Marlowe Playground, which you can find out more about in the section about xref:playground-overview#playground-overview[], select *New Project* and then *Blockly* for the project type. You'll now see a screen like this:
 
 image:blockly1.png[Blockly window]
 
 Contracts are assembled by adding components to the holes in the blocks. To build a contract, we have to fill the single, top-level, hole here with a `Contract`, and blocks for these are found by clicking on *Contracts* in the menu on the left hand side. Doing this shows all the different blocks that build contracts, as shown here:
 
 image:blockly2.png[Contracts in Blockly]
 
-We can select one and drag it into the pane, like this:
+We can select one and drag it into the editing area, which has a dotted background, like this:
 
 image:blockly3.png[A contract block]
 
 and then fit it into the top-level hole, so that we're constructing a contract with a `When` as its main construct.
 
 image:blockly4.png[Fitting in a contract block]
+
+We can then repeat this process, adding contracts and other types of components – all of which are shown in the menu on the left-hand side – to build a complete contract, that is a contract that contains no holes.
 
-This is the process that we repeat, adding contracts and other types of components – all shown in the menu on the left-hand side – to build a complete contract.
-
-Let's fill in the timeout information and put a `Close` contract to perform on timeout:
+Let's fill in the timeout information and add a `Close` contract to be performed in the case of timeout:
 
 image:blockly5.png[Adding timeout information]
 
@@ -42,7 +42,7 @@ Here we have to choose
 * A *Role* for the depositor
 * A *Value* which is the amount deposited …
 * … in the *Token* (often *ada*)
-* Whose account, another *Role*, into which the money is deposited.
+* Where the money is to be deposited, give by a *Party*, which is either a *Role* or a *Public Key*.
 
 In filling in some of these we have also to fill in a text field, or a number, as shown in the final result here.
 

marlowe/doc/playground-overview.adoc

@@ -37,7 +37,7 @@ The landing page for the Marlowe Playground looks like this
 
 image:landing-page.png[The landing page for the Playground]
 
-The title bar has, at the right hand side, links to this tutorial and the Actus Labs feature, and the *main menu* operations are shown below this.
+The title bar has, at the right-hand side, links to this tutorial and the Actus Labs feature, and the *main menu* operations are shown below this.
 
 * *New Project* This clears the existing project, and creates a new one, in a coding environment of the user's choice:
 
@@ -60,13 +60,13 @@ The editor supports the development of Marlowe contracts described in Haskell. W
 
 image:haskell-editor.png[The Haskell editor]
 
-The Haskell editor is open here on the Escrow example contained in the examples. To describe a Marlowe contract in the editor, we have to define a top-level value `contract` of type `Contract`; it is this value that is converted to pure Marlowe with the *Compile* button (in the top RH corner). If compilation is successful, the compiled code is shown in an overlay (which can be minimised):
+The Haskell editor is open here on the Escrow example contained in the examples. To describe a Marlowe contract in the editor, we have to define a top-level value `contract` of type `Contract`; it is this value that is converted to pure Marlowe with the *Compile* button (in the top right-hand corner). If compilation is successful, the compiled code is shown in an overlay (which can be minimised):
 
 image:haskell-compiled.png[Haskell code compiled to Marlowe]
 
-On successful compilation the result can be sent to the simulator or to Blockly: these options are provided by the *Send to Simulator* and *Send to Blockly* buttons in the top RH corner of the page.
+On successful compilation the result can be sent to the simulator or to Blockly: these options are provided by the *Send to Simulator* and *Send to Blockly* buttons in the top right-hand corner of the page.
 
-If the contract cannot successfully be converted to Marlowe, the errors are also shown in overlay:
+If the contract cannot successfully be converted to Marlowe, the errors are also shown in an overlay:
 
 image:haskell-errors.png[Errors in compiling Haskell code to Marlowe]
 
@@ -77,20 +77,22 @@ The editor supports the development of Marlowe contracts described in JavaScript
 
 image:js-editor.png[The JavaScript editor]
 
-The JS editor is open here on the Escrow example contained in the examples. To describe a Marlowe contract in the editor, the _last expression in the file_ needs to be of type  `Contract`: here we define the top-level constant `contract` to be of that type. 
+The JS editor is open here on the Escrow example contained in the examples. To describe a Marlowe contract in the editor, the variable `contract` needs to be defined to something of type  `Contract`. 
 
-image:js-editor-cont.png[The final expression in the editor defines the contract.]
+image:js-editor-cont.png[The value of `contract` defines the contract.]
 
 The editor supports auto-complete, error checking during editing, and information about bindings on mouse over. In particular, using mouse over on any of the imported bindings will show its type (in TypeScript).
 
-It is this final value that is converted to pure Marlowe with the *Compile* button (in the top RH corner). If compilation is successful, the compiled code is shown in an overlay (which can be minimised):
+When you click the *Compile* button (in the top right-hand corner), the code in the editor is executed, and the JSON object in the variable `contract` resulting from the execution is parsed into an actual Marlowe contract that can then be sent to the Simulation tab where it can be simulated.
+
+If compilation is successful, the compiled code is shown in an overlay (which can be minimised):
 
 image:js-compiled.png[JS code compiled to Marlowe]
 
 On successful compilation the result can be sent to the simulator using the *Send to Simulator*  
-button in the top RH corner of the page.
+button in the top right-hand corner of the page.
 
-If the contract cannot successfully be converted to Marlowe, the errors are also shown in overlay:
+If the contract cannot successfully be converted to Marlowe, the errors are also shown in an overlay:
 
 image:js-error.png[Errors in compiling JS code to Marlowe]
 
@@ -100,15 +102,15 @@ The playground provides a mechanism for creating and viewing contracts in a visu
 
 === Developing contracts in Marlowe
 
-It is also possible to create contracts in "raw" Marlowe too, and this is performed in the simulation environment. Marlowe is edited in the Monaco editor, and this gives formatting (on right click) and supports *holes* too. 
+It is also possible to create contracts in "raw" Marlowe too, and this is performed in the simulation environment. Marlowe is edited in the Monaco editor, and this gives automatic  formatting (on right click) and supports *holes* too. 
 
 image:marlowe-editor.png[Editing Marlowe: using holes]
 
 Holes allow a program to be built top-down. Clicking the lightbulb next to a hole presents a completion menu, in each case replacing each sub component by a new hole. For example, choosing `Pay` to fill the top-level hole will result in this:
 
 image:marlowe-hole-fill.png[Editing Marlowe: filling a hole]
 
-Holes can be combined with ordinary text editing, so that you can use a mixture of bottom-up and top-down constructs in building Marlowe contracts. Moreover, contracts with holes can be transferred to and from Blockly: holes in Marlowe become literal holes in Blockly. To transfer to Blockly use the *View in Blockly Editor* in the top RH corner of the screen.
+Holes can be combined with ordinary text editing, so that you can use a mixture of bottom-up and top-down constructs in building Marlowe contracts. Moreover, contracts with holes can be transferred to and from Blockly: holes in Marlowe become literal holes in Blockly. To transfer to Blockly use the *View in Blockly Editor* in the top right-hand corner of the screen.
 
 === Simulating Marlowe contracts
 
@@ -125,15 +127,15 @@ image:available-actions.png[The actions available, width=300]
 In this case there are two potential actions: Alice can make a deposit, or the slot (time) can advance to `10` at which the wait for a deposit times out. Two other generic actions can be taken too
 
 * *Undo* will undo the last action made in the simulator. This means that we can explore a contract interactively, making some moves, undoing some of them, and then proceeding in a different direction.
-* *Reset* will reset the contract and its state back to their initial values: the full contract and an empty state.
+* *Reset* will reset the contract and its state back to their initial values: the full contract and an empty state. It also _stops_ the simulation.
 
 For our example, let us select for Alice to make the deposit of 450 lovelace. We can do that with the *+* button next to this input. After doing that we see
 
 image:simulation2.png[Simulation step 2]
 
 Where we see at the foot of the screen that the deposit has taken place. 
 
-This remains in view if we then make Alice's and then Bob's choice. Note also the the current state of the contract is shown in the main part of the window, and indeed we are waiting at this stage for a choice from Alice.
+This remains in view if we then make Alice's and then Bob's choice. Note also that the current state of the contract is shown in the main part of the window, and indeed we are waiting at this stage for a choice from Alice.
 
 If Alice and Bob make different choices we then see
 
@@ -143,11 +145,11 @@ and at this point in the evolution of the contract we are awaiting a choice from
 
 === Saving and Opening Projects
 
-Projects are saved on github, and so when you first save a project you will be prompted thus:
+Projects can be saved on github, and so when you first save a project you will be prompted thus:
 
 image:github1.png[Prompt to login to github]
 
-and if you choose to *Login* there you will be taken to a login screen for github:
+and, if you choose to *Login* there, you will be taken to a login screen for github:
 
 image:github2.png[Logging in to github,width=300]