diff --git a/docs/basics.rst b/docs/basics.rst
index 1f083e6551035ebbd887fa1564dd7bdc01a74386..42a4f1543e32a1c08ce5583dbbba2e7d01a3820b 100644
--- a/docs/basics.rst
+++ b/docs/basics.rst
@@ -7,6 +7,9 @@ the top folder of the tutorial.
 Compose fireworks and workflows
 -------------------------------
 
+Formats and editors
+~~~~~~~~~~~~~~~~~~~
+
 Fireworks and Workflows can be defined in three different general-purpose 
 languages: Python, JSON and YAML. There is no domain-specific language for 
 FireWorks and thus no specialized editor. This is why, a normal text editor is 
@@ -16,10 +19,18 @@ is "nice to have".
 All workflow definitions in all exercises will be based on JSON and YAML. 
 Exercise 5 will introduce to writing a custom Firetask for which 
 Python will be used. Again, JSON and YAML will be used to define the workflows 
-using the custom Firetask. For each exercise there are one or more initial 
+using custom Firetasks. For each exercise there are one or more initial 
 examples in the **exercises/demos** folder. We recommend trying these examples 
 before starting solving the problems.
 
+**NOTE:** Most of the examples here will be presented in YAML (more readable and
+concise). If you feel more comfortable with editing JSON you can use the converters 
+``yaml2json`` and ``json2yaml`` provided in the **bin** folder or/and the provided
+JSON versions of the demos and solutions.
+
+Workflow structure
+~~~~~~~~~~~~~~~~~~
+
 The building blocks of a workflow are the fireworks. The firework is the minimum 
 possible piece of the worklfow executed by the rocket launcher (see execution_). 
 The major part of the workflow description is the list of fireworks, ``fws``. 
@@ -60,7 +71,7 @@ Here is a short example of a workflow, demonstration the use of the
     metadata: {}
     name: Simple coffee workflow
 
-Open a text editor, such as *vi*, *nano*, *gedit* or *emacs*, and save the 
+Open a text editor, such as ``vi``, ``nano``, ``gedit`` or ``emacs``, and save the 
 example above as **workflow.yaml**.
 
 
@@ -73,9 +84,9 @@ life cycle.
 When used productively the LaunchPad contains many workflows in different states. 
 To distinguish between different workflows, the query commands can specify e.g.
 the firework ID from the relevant workflow on the LaunchPad or perform a 
-mongo-like queries. To avoid the need apply filters to the queries, at the 
-beginning of each exercise in this tutorial we will clean up the LaunchPad from 
-previous fireworks with this command::
+mongo-like queries. To avoid the need to apply filters to the queries, we will 
+clean up the LaunchPad from previous fireworks at the beginning of each exercise 
+in this tutorial with this command::
 
     lpad reset
 
@@ -96,10 +107,9 @@ at this stage and the errors appear at run time. To also check for such errors
 the *-c* or *--check* flags can be used when adding the workflow to the 
 LaunchPad::
 
-
     lpad add -c workflow.json
 
-If a workflow has been added without check it can be check later with::
+If a workflow has been added without such a check, it can be checked later with::
 
     lpad check_wflow -i <firework ID>
 
@@ -144,9 +154,9 @@ fireworks are completed (state *COMPLETED*) and the states of linked child
 fireworks are updated as soon as a firework if completed. This means that any 
 workflow will be run until there are no more fireworks in *READY* state.
 
-**NOTE:** In singleshot mode ``rlaunch`` runs the firework in the directory where it is 
-started. In rapidfire mode ``rlaunch`` creates a runtime sibdirectory one per firework 
-and executes each firework in a separate directory.
+**NOTE:** In singleshot mode ``rlaunch`` runs the firework in the directory 
+where it is started. In rapidfire mode ``rlaunch`` creates separate per-firework 
+sub-directories at run time in which the fireworks are executed.
 
 To suppress verbose information on the screen the *-s* flag can be added::