diff --git a/docs/compile.md b/docs/compile.md
index fde4a501d7..93a2d725e4 100644
--- a/docs/compile.md
+++ b/docs/compile.md
@@ -5,7 +5,7 @@ Clicking the Solidity icon in the icon panel brings you to the Solidty Compiler.
 
 Compiling is triggered when you click the compile button ( **D. in image below**). If you want the file to be compiled each time the file is saved or when another file is selected - check the auto compile checkbox ( **E. in image below**).
 
-Since the Solidity version `0.5.7`, it is possible to compile `Yul` files. Please read the (([solidity documentation about Yul]https://solidity.readthedocs.io/en/latest/yul.html)) which contain some code examples.
+Since the Solidity version `0.5.7`, it is possible to compile `Yul` files. Please read the ([solidity documentation about Yul](https://solidity.readthedocs.io/en/latest/yul.html)) which contain some code examples.
 You can use the language dropdown ( **B. in image below**) to switch the language. **This dropdown list is only available for versions greater than or equal to `0.5.7`.**
 
 The fork selection dropdown list ( **C. in image below**) allows to compile code against a specific ethereum hard fork. 
@@ -15,15 +15,15 @@ If the contract has a lot of dependencies it can take a while to compile - so yo
 
 ![](images/a-sol-compiler.png)
 
-After each compilation, a list is updated with all the newly compiled
-contracts.  The contract compiled can be selected with the Contract pulldown menu ( **F. in image below**).  Multiple contracts are compiled when one contract imports other contracts.  Selecting a contract will show information about that one.
+After each compilation, a list is updated with all newly compiled
+contracts.  A compiled contract can be selected with the Contract pulldown menu ( **F. in image below**).  Multiple contracts are compiled when one contract imports other contracts.  Selecting a contract will show information about that one.
 
 When the "Compilation Details" button is clicked ( **G. in image below**), a modal opens displaying detailed information about the current selected contract.
 
 From this tab, you can also publish your contract to Swarm (only non
 abstract contracts can be published).
 
-Published data notably contains the `abi` and solidity source code.
+Published data notably contains the `abi` and the solidity source code.
 
 After a contract is published, you can find its metadata information
 using the bzz URL located in the details modal dialog `SWARM LOCATION`.
diff --git a/docs/contract_metadata.md b/docs/contract_metadata.md
index 4806e30cd3..46dcc40832 100644
--- a/docs/contract_metadata.md
+++ b/docs/contract_metadata.md
@@ -1,13 +1,13 @@
 Build Artifact
 ==============
 
-As compilation succeed Remix create a JSON file for each compiled contract.
+As compilation succeeds Remix creates a JSON file for each compiled contract.
 These JSON files contains several metadata
 
 Library Deployment
 ------------------
 
-By default Remix automatically deploy needed libraries.
+By default Remix automatically deploys needed libraries.
 
 `linkReferences` contains a map representing libraries which depend on the current contract. 
 Values are addresses of libraries used for linking the contract.
diff --git a/docs/create_deploy.md b/docs/create_deploy.md
index 6bff42f6ea..6934c71998 100644
--- a/docs/create_deploy.md
+++ b/docs/create_deploy.md
@@ -29,7 +29,6 @@ Sample contract
 ---------------
 
 ``` 
-{.sourceCode .none}
 pragma solidity ^0.5.1;
 
 contract testContract {
@@ -62,7 +61,7 @@ Deploying an instance
 ---------------------
 
 The `Compile tab` displays information related to the current contract
-(note that there can be more than one) (see ../compile\_tab).
+(note that there can be more than one) ([see compile](compile.html)).
 
 Moving on, in the `Run tab` select, `JavaScript VM` to specify that you
 are going to deploy an instance of the contract in the `JavaScript VM`
diff --git a/docs/import.md b/docs/import.md
index a576d24586..8d2c030b1e 100644
--- a/docs/import.md
+++ b/docs/import.md
@@ -1,9 +1,9 @@
 Importing Source Files in Solidity
 ==================================
 
-It is essential to know all many techniques for importing files.
+It is essential to know many techniques for importing files.
 
-For a tutorial about importing files see this [tutorial](https://github.com/ethereum/remix-workshops/tree/master/loading_via_npm_github_plugin).
+For a tutorial about importing files click [here](https://github.com/ethereum/remix-workshops/tree/master/loading_via_npm_github_plugin).
 
 For a detailed explanation of the `import` keyword see the
 [Solidity documentation](https://solidity.readthedocs.io/en/develop/layout-of-source-files.html?highlight=import#importing-other-source-files)
@@ -13,7 +13,7 @@ Here are a some of the main methods of importing a file:
 Importing a file from the browser's local storage
 -------------------------------------------------
 
-Files in Remix can be imported just by specifying their path. Please use ./ for relative paths to increase portability.
+Files in Remix can be imported just by specifying their path. Please use ```./``` for relative paths to increase portability.
 ![](images/a-old-tuto_basicimport.png)
 
 Importing a file from your computer's filesystem
diff --git a/docs/remix_commands.md b/docs/remix_commands.md
index e93f495d9b..78ddd0758a 100644
--- a/docs/remix_commands.md
+++ b/docs/remix_commands.md
@@ -1,7 +1,7 @@
 Remix Commands
 ==============
 
-In the console, you can run the commands listed below.  Once you start to type a command, there is *auto completion*.  These commands are using the following programs:
+In the console, you can run the commands listed below.  Once you start to type a command, there is *auto completion*.  These commands are using the following libraries:
 
 + *ethers*: The [ethers.js](https://docs.ethers.io/ethers.js/html/getting-started.html) library is a compact and complete JavaScript library for Ethereum. 
 
diff --git a/docs/run.md b/docs/run.md
index 62a8e8fd1c..c06630fbc9 100644
--- a/docs/run.md
+++ b/docs/run.md
@@ -61,10 +61,10 @@ This section contains the list of compiled contracts and 2 actions:
 Pending Instances
 -----------------
 
-Validating a transaction take several seconds. During this time, the GUI
-shows it in a pending mode. When transaction is mined the number of
+Validating a transaction takes several seconds. During this time, the GUI
+shows it in a pending mode. When the transaction is mined the number of
 pending transactions is updated and the transaction is added to the log
-(see ../terminal)
+([see terminal](terminal.html)).
 
 Using the ABI
 ------------
@@ -89,15 +89,15 @@ Saving to JSON allows to easily check the transaction list, tweak input
 parameters, change linked library, etc...
 
 We can find many use cases for the recorder, for instance:
-:   -   After having coded and tested contracts in a constrained
-        environment (like the JavaScript VM), it could be interesting to
-        redeploy them easily in a more persisted environment (like a
-        Geth node) in order to check whether everything behaves normally
-        in a classic environment.
-    -   Deploying contract does often require more than creating one
-        transaction.
-    -   Working in a dev environment does often require to setup the
-        state in a first place.
+-   After having coded and tested contracts in a constrained
+    environment (like the JavaScript VM), it could be interesting to
+    redeploy them easily in a more persisted environment (like a
+    Geth node) in order to check whether everything behaves normally
+    in a classic environment.
+-   Deploying contract does often require more than creating one
+    transaction.
+-   Working in a dev environment does often require to setup the
+    state in a first place.
 
 ![](images/a-runtab-recorder.png)
 
@@ -108,19 +108,19 @@ In that specific record, 3 transactions are executed:
 
 The first corresponds to the deployment of the lib `testLib`.
 
-The second corresponds to the deployment of the contract `test`, the
-first parameter of the constructor is set to 11. That contract depends
+The second corresponds to the deployment of the contract `test` with the
+first parameter of the constructor set to 11. That contract depends
 on a library. The linkage is done using the property `linkReferences`.
-In that case we use the addres of the previously created library :
-`created{1512830014773}`. the number is the id (timestamp) of the
-transaction that leads to the creation of the library.
+In that case we use the address of the previously created library :
+`created{1512830014773}`. The number is the id (timestamp) of the
+transaction that led to the creation of the library.
 
-The third parameter corresponds to the call to the function `set` of the
+The third record corresponds to the call to the function `set` of the
 contract `test` (the property to is set to: `created{1512830015080}`) .
 Input parameters are `1` and
 `0xca35b7d915458ef540ade6068dfe2f44e8fa733c`
 
-all these transactions are created using the value of the accounts
+All these transactions are created using the value of the accounts
 `account{0}`.
 
 ``` 
diff --git a/docs/udapp.md b/docs/udapp.md
index fae2791044..a225d7b238 100644
--- a/docs/udapp.md
+++ b/docs/udapp.md
@@ -17,8 +17,7 @@ You will see the functions in the contract.  The functions buttons can have diff
 
 -   Functions that are `constant` or `pure` functions in Solidity have a blue buttons. Clicking one of this type does not create a new transaction. So clicking will not cause state changes - it will only return a value stored in the contract - so it won't cost you anything in gas fees.
 
--   Functions that changes the state of the contract are orange, clicking this type of function will cost gas and they do change the state of the contract and so they do create a new transaction.
-But this transaction does not accept Ether.
+-   Functions that change the state of the contract AND that do not accept Ether are called `non-payable` functions and have an orange button. Clicking on them will create a transaction and thus cost gas.
 
 -   Functions that have red buttons are `payable` functions in Solidity. Clicking one of these will create a new transaction and this transaction can accept a **value**.  The **value** is put in in the Value field which is under the Gas Limit field.
 
diff --git a/docs/unittesting.md b/docs/unittesting.md
index 27720f7f38..187755a60a 100644
--- a/docs/unittesting.md
+++ b/docs/unittesting.md
@@ -14,7 +14,9 @@ This file contains the minimun you need for running unit testing.
 Run Tests
 ---------
 
-This execute tests. The execution is run in a separate environment and the result is displayed below.
+This executes all tests whose box has been checked below (by default all). The execution is run in a separate environment and the result is displayed below.
+
+Here is a list of functions and their supported types that you can use to write your testcases:
 
 | Available functions  | Supported types |