diff --git a/themes/getting-started/setup-env.rst b/themes/getting-started/setup-env.rst
index be7c139ab6..73c0eb52cc 100644
--- a/themes/getting-started/setup-env.rst
+++ b/themes/getting-started/setup-env.rst
@@ -1,29 +1,34 @@
 ****************
-Setup Env
+Setting up your environment
 ****************
 
-isntall prsetashop
+Installing PrestaShop
 ====================
 
-1. git clnoe
-1. composer install
-1. npm install
+We advise you to install PrestaShop using the Composer and npm tools.
+For this, you must download Composer and Node.js (which contains npm), and install them.
 
+Then, open a command line on your (empty) working directory, then
 
-gitignore
+1. git clone https://github.com/PrestaShop/PrestaShop.git
+2. composer install
+3. npm install
+
+
+Building your .gitignore
 ============
 
-To redo from: http://build.prestashop.com/howtos/misc/prestashop-perfect-gitignore/
+// TODO To redo from: http://build.prestashop.com/howtos/misc/prestashop-perfect-gitignore/
 
 
-Create your theme from starter themes
+Create your theme from the Starter Theme
 =======================================
 
-1. download Starter theme or clone the repo
-1. remove all style if any (if you clone)
-1. cp theme.yml.dist
-1. edit theme.yml
-1. cd _dev + npm install
+1. Download the Starter Theme, or clone its repo (https://github.com/PrestaShop/StarterTheme.git)
+  1. If you clone, remove all the 
+2. cp theme.yml.dist
+3. edit theme.yml
+4. cd _dev + npm install
 
 
 NOTE compile sass, you can change according to your choices
diff --git a/themes/getting-started/starter-theme.rst b/themes/getting-started/starter-theme.rst
index 8f2e0638be..d1f2a3fd06 100644
--- a/themes/getting-started/starter-theme.rst
+++ b/themes/getting-started/starter-theme.rst
@@ -2,42 +2,45 @@
 Starter Theme
 ****************
 
+PrestaShop 1.7 introduces a new way for designers to create their theme from scratch: the Starter Theme.
+The default theme for PS 1.7 is based on the Starter Theme.
 
-For pretty much every CMS, the default theme is used as a framework to build theme.
+For pretty much every CMS, the default theme is used as a framework to build custom theme: designers have to rework the default theme and reshape it into what they want to display. Sometimes that means having to spend a lot of time removing all the CSS rules and JavaScript code from the default theme, and rewriting everything. This means a LOT of work before even starting to actually create something original.
 
-This means all theme are tied to most of our technical choices. if we use bootstrap it's hard to
-use foundation for instance.
+This means that a lot of themes are tied to the default theme's technical choices, because this way of working makes it hard to make your own choices. For instance, since the default theme uses Bootstrap, it's hard to use Foundation.
 
-We decided to build a theme that will let you start your theme with all the minimum code: template files, markup ad JavaScript.
+With the Starter Theme, the PrestaShop team decided to build a skeleton theme that will give you a kickstart for your custom theme, with all the minimum code (essential template files, markup ad JavaScript code) and enough freedom to make your own choices. You can choose to use Bootstrap, Foundation or Blueprint. The Starter Theme is not opinionated: there is no decision made to use either one library or another.
 
-The Starter Theme is not opinionated, there is no decision made to use either this lib or another one.
+By using the Starter Theme as the foundation for your custom theme, everything is ready for you, you just have to create upon it.
 
-If you download the release of StarterTheme, everything is ready for you.
 
-If you clone the StarterTheme repo you will see he startertheme as some minimalistic (ugly ?) style. This is only for deelopement purpose. You shouldnt use them or inlcude them in your theme, please delete all files inside `_dev/css` (see screenshot)
+Downloading the Starter Theme
+================
 
-[WARNING]
-Unless your remove it, jQuery is loaded inside core.js
+The Starter Theme is available on GitHub: https://github.com/PrestaShop/StarterTheme
+
+If you clone the StarterTheme repository and select it as the theme for your store, you will see minimalistic theme with an overly simplistic (ugly?) style. This is only for devlopement purpose. You should NOT use the Starter Theme as is, and you should NOT use its default CSS rules nor include them in your theme: please delete all files inside `_dev/css` (see screenshot)
 
+[WARNING]
+Unless your remove it, the jQuery library is loaded by the core.js file.
 
 [NOTE]
-Please note that if you want to sell your theme on addons, there are some specific requirements, like you must use bootstrap.
-See more: link
+Please note that if you want to sell your theme on the PrestaShop Addons marketplace, there are some specific requirements. For instance, Addons-distributed themes MUST use Bootstrap.
 
+See more: 
+// TODO add addons link
 
-Modify. don't override.
+
+Modify. Don't override.
 ============================
 
-When you want to create a new theme, copy and paste all files from the starter theme inside your empty theme directory.
-then start modifying it.
+When you want to create a new theme, copy and paste all files from the Starter Theme inside your empty theme directory.
+Then you start modifying it, and building your own theme.
 
 Do not use it as a parent theme, you will only run into trouble and waste your time.
 
-
-[BUTTON DOWLOAD STARTERTHEEM]
+[BUTTON DOWNLOAD STARTERTHEME]
 
 [SCREENSHOT NO STYLE vs DEV STYLE]
 
-
-Read also
-http://build.prestashop.com/tag/starter-theme/
+Read also: http://build.prestashop.com/tag/starter-theme/
diff --git a/themes/getting-started/theme-organization.rst b/themes/getting-started/theme-organization.rst
index 3f447e3221..78f40c1422 100644
--- a/themes/getting-started/theme-organization.rst
+++ b/themes/getting-started/theme-organization.rst
@@ -1,11 +1,11 @@
 ****************
-THEME organization
+Theme organization
 ****************
 
-directory structure
+Directory structure
 ========================
 
-A detailler !
+// TODO Needs more details!
 
 .. code-block::
 
@@ -70,15 +70,15 @@ A detailler !
       └── wrapper.tpl
 
 
-required templates and libs
+Required templates and libraries
 ============================
 
 Required templates
 --------------------
 
-When you install/enable a theme, PRsetaShop will check if the theme is valid. It's looking looking for theme.yml file (and check its content), declared compatibility and some template files.
+When you install/enable a theme, PrestaShop will check if the theme is valid: it looks for theme.yml file (and checks its content), its declared compatibility, and some template files.
 
-Here is the exhaustive and up-to-date (lol) file list:
+Here is the complete list of files that are checked:
 
 * preview.png
 * config/theme.yml
@@ -96,13 +96,9 @@ Here is the exhaustive and up-to-date (lol) file list:
 
 
 [NOTE]
-All these files need to exists, even if they're empty.
-maybe you've built some sort of ground breaking theme and it doesnt exactly work like the starter theme does. Like you don t have any product page, then you don't want the product.tpl file. You just have to create an empty one. be nice and add a comment to were the code related to products can be found ;)
+All these files need to exist, even if they're empty.
+It could be that you've built some sort of groundbreaking theme and it doesn't exactly work like the Starter Theme does. For instance, you don't have need a product page, then you don't want the product.tpl file. In that case, you just have to create an empty product.tpl file. Be nice to the next develop and add a comment indicating where the code related to products can be found ;)
 
+jQuery is already loaded with the core.js file, but no other libraries, since the idea is that the Starter Theme should not opinionated.
 
-
-
-jQuery is already loaded with core.js
-but no other lib since not opinionated
-
-[note] block sur addons
+// TODO add info about Addons block
diff --git a/themes/getting-started/theme-yml.rst b/themes/getting-started/theme-yml.rst
index a5f71e1c84..b2e0bb2261 100644
--- a/themes/getting-started/theme-yml.rst
+++ b/themes/getting-started/theme-yml.rst
@@ -2,14 +2,14 @@
 Theme.yml
 ****************
 
-The theme. yml defines all the theme configuration like version number, layouts, compatibility range, hook configuration...
+The theme's theme.yml file defines all of the theme's configuration and meta information, such as its version number, layouts, compatibility range, hook configuration, etc.
 
-theme description
+Theme description
 =========================
 
-Name must match directory name
+The theme's name MUST match its directory name. For instance, if the theme is named "My Awesome Theme" and its 'name' value is set to "my-awesome-theme", then the folder MUST be /my-awesome-theme .
 
-Users will be able to choose each page's layout from the theme's settings page. Layouts are automatically parsed from the templates/layouts folder so this configuration key is optional, but it allows designers to provide some more user friendly info than just a filename.
+Users will be able to choose the layout for each page from the theme's settings page. Layouts are automatically parsed from the theme's /templates/layouts folder, so this configuration key is optional, but it allows designers to provide some more user-friendly info than just a filename.
 
 .. code-block:: yaml
 
@@ -36,10 +36,10 @@ Users will be able to choose each page's layout from the theme's settings page.
 Global settings
 ====================
 
-configuration
+Configuration
 ------------------
 
-change PrestaShop configuration when the theme is enabled
+You can have the theme change the configuration of PrestaShop when the theme is enabled.
 
 .. code-block:: yaml
 
@@ -55,6 +55,8 @@ change PrestaShop configuration when the theme is enabled
 Modules
 ----------------------
 
+You can have the theme enable or disabled modules when the theme is enabled.
+
 .. code-block:: yaml
 
   global_settings:
@@ -71,6 +73,7 @@ Modules
         - homeslider
         - blockwishlist
 
+You can also have the theme create hooks and attach modules to custom and existing hooks when the theme is enabled.
 
 global_settings:
   hooks:
@@ -115,7 +118,8 @@ global_settings:
 Image settings
 --------------------
 
-When theme will be enabled, all image types will be removed Template must declare their image type.
+Enabling the theme will remove all the existing image types.
+Themes MUST declare their image types, and what they apply to.
 
 .. code-block:: yaml
 
@@ -158,9 +162,11 @@ When theme will be enabled, all image types will be removed Template must declar
 Theme settings
 ---------------------
 
-All the settings below can be changed through an interface in the theme's administration panel, and only depend on the theme / shop combination.
-When this file is parsed by PrestaShop, this configuration key (theme_settings) is copied to a file name settings_n.yml where n is the id of the shop where the theme is installed.
-When configuration is changed through the interface, only the settings_n.yml file is updated and theme.yml remains unchanged.
+All the settings below can be changed through an interface in the theme's back office interface, and only depend on the theme / shop combination.
+
+When this file is parsed by PrestaShop, the 'theme_settings' configuration key is copied to a file named settings_n.yml, where n is the id of the shop where the theme is installed (settings_my-awesome-theme.yml, for instance).
+
+When the configuration is changed through the back office interface, only the settings_n.yml file is updated - the theme.yml file remains unchanged.
 
 .. code-block:: yaml
 
diff --git a/themes/hooks/hooks.rst b/themes/hooks/hooks.rst
index 8bb3ddea16..095728d65f 100644
--- a/themes/hooks/hooks.rst
+++ b/themes/hooks/hooks.rst
@@ -2,40 +2,42 @@
 Hooks
 ***********
 
-Im only talking about front Hooks: displya and action
+This section of the documentation is only about front office hooks: display and action.
 
 All Hooks
 ------------
 
-INCLUDE JSON
+// TODO include the content of the hooks.json 
 
 
-Create custom hook
+Creating a custom hook
 --------------------
 
-Dynamic Hooks
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Creating a dynamic hook
+^^^^^^^^^^^^^^^^^^^^^^^
 
-When you call a hook, prestashop will execute it
+When your module or theme calls a hook, PrestaShop executes it.
 
-Smarty:
+From a regular PHP file:
 
-.. code-block:: Smarty
+.. code-block
 
-  {hook h='MyCustomHookThatNobodyUses'}
+  Hook::exec('MyCustomHook');
 
 
-.. code-block
+From a Smarty template:
 
-  Hook::exec('MyCustomHookThatNobodyUses');
+.. code-block:: Smarty
+
+  {hook h='MyCustomHook'}
 
 
-Declared, visible and reusable
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Making your hook visible and reusable
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-If you want the user to be able to see it in Position page, it has to be registered
+If you want the user to be able to see your hook in PrestaShop's Position page (in the back office), it has to be registered.
 
-register in in your theme
+You can register your hook from your theme.
 
 [SEE] theme-yml
 
@@ -49,10 +51,17 @@ register in in your theme
           description: Add a widget area above the footer
 
 
-register it in your module
+You can also register your hook from your module.
 
 .. code-block:: php
+  // Create the function for the MyCustomHook hook
+  public function MyCustomHook($params) 
+  {
+      // method body
+  }
+
+  // Register the MyCustomHook hook
+  Hook::register('MyCustomHook');
 
-  Hook::register(xx);
-  // call it
-  Hook::exec('MyHook');
+  // Call it from PHP
+  Hook::exec('MyCustomHook');
diff --git a/themes/overriding-modules/overriding.rst b/themes/overriding-modules/overriding.rst
index 9b6b1d489e..88097399e2 100644
--- a/themes/overriding-modules/overriding.rst
+++ b/themes/overriding-modules/overriding.rst
@@ -1,13 +1,15 @@
 **************************************
-Overrideing modules
+Overriding modules
 ***************************************
 
 
-When you write a theme, you will need to override some module templates and assets if they need to match a specific markup.
+When you write a theme, you often need to override templates and assets from a module so that they match your theme's specific markup needs.
+Theme can override module assets (CSS and JavaScript only) by placing the corresponding file at a specific location.
 
-With PrestaShop 1.7 all module override goes to the `modules` directory.
+With PrestaShop 1.7, all module override code goes to the `modules` directory (in your module's own directory).
+Every PS 1.7 module developer should be aware of this change (introduced with PR 5020: https://github.com/PrestaShop/PrestaShop/pull/5020).
 
-Example with this module directory structure
+Examples in this page are based on this sample module directory structure:
 
 .. code-block:: tree
 
@@ -27,11 +29,10 @@ Example with this module directory structure
   5 directories, 6 files
 
 
-Override template or assets
+Overriding templates and assets
 ============================
 
-
-With PS 1.7
+With PrestaShop 1.7, here is the paths to create in order to override templates and assets:
 
 .. code-block:: tree
 
@@ -51,7 +52,7 @@ With PS 1.7
   6 directories, 5 files
 
 
-With PRestaShop 1.6
+Compare with what was needed in PrestaShop 1.6:
 
 .. code-block:: tree
 
@@ -74,40 +75,33 @@ With PRestaShop 1.6
 
   10 directories, 5 files
 
-https://github.com/PrestaShop/PrestaShop/pull/5020
-
-
-With include
-==============
 
-Very important. When loading a template, prestashop will look for override first.
+Overriding with the 'include' method
+==============================
 
-Order:
+There is one very important issue that you should be aware of.
+When loading a template file (for instance 'moduledemo.tpl'), PrestaShop will look for overriding first, in the following order:
 
 1. /themes/THEME_NAME/modules/MODULE_NAME/views/templates/front/moduledemo.tpl
-1. /modules/MODULE_NAME/views/templates/front/moduledemo.tpl
+2. /modules/MODULE_NAME/views/templates/front/moduledemo.tpl
 
-But if your file `moduledemo.tpl` include the file `included-template.tpl`, you will have to override it as well, even if you dont want to modify it (or edit the path)
+But if your `moduledemo.tpl` file includes the `included-template.tpl` file, you will have to override 'included-template.tpl' as well, even if you don't want to modify it (nor to edit the path). This means that every file that an overridden file includes needs to be copy-paster as-is in order for your override to work properly.
 
-The problem goes both ways if you want to modify the `included-template.tpl`, you will have to override `moduledemo.tpl`.
+The issue goes both ways: if you want to modify the `included-template.tpl` file, you will have to override the `moduledemo.tpl` file that includes it.
 
-
-.. code-block:: smarty
+.. code-block:: Smarty
 
   {include file='./included-template.tpl'}
 
-PrestaShop introduce a new cool way to onlcude files in module tempaltes, all rules will be followed
+  
+PrestaShop introduce a new cool way to include files in module templates? By using this method, all the expected rules will be followed:
 
-.. code-block:: smarty
+.. code-block:: Smarty
 
   {include file='module:MODULE_NAME/views/templates/front/included-template.tpl'}
 
 
+SmartyDev helps you debug!
+==========================
 
-[NOTE TO MODULE DEVELOPER]
-USE IT !!!!!
-
-
-[INFO]
-see the template path in html sources
-https://github.com/PrestaShop/PrestaShop/pull/5105
+PrestaShop 1.7 introduces SmartyDev, an extension of Smarty which allows you to see the template name within your markup. To use it, simply enable the _PS_MODE_DEV_: in your installation's /config/defines.inc.php file, add the 'define('_PS_MODE_DEV_', true);' to turn the Developer Mode on.
\ No newline at end of file
diff --git a/themes/partials/notifications.rst b/themes/partials/notifications.rst
index df99f9edb3..0a82317ed0 100644
--- a/themes/partials/notifications.rst
+++ b/themes/partials/notifications.rst
@@ -1,31 +1,33 @@
-notifications
+Notifications
 ================
 
-Throughout the whole site user get flash notifications messages from PRestaShop to inform him about success or error
+Throughout the whole front office, the customer can receive notification messages from PrestaShop, to inform her about successes or errors, for instance.
+Your theme can too send notifications.
 
-No message is hardcoded to the template. All message from controller so we have consistency in case you updage/change template
-Plus there is a good chance all messages are already translated in your language
+The notification messages are not hardcoded in the template, but are send from the controller, so that you have consistency in case you updage/change your template.
+Also, there is a good chance that all messages are already translated into your language!
 
-4 types of notifications
------------------------------
 
-An array of notification is passed to the templates, containing:
+Types of notifications
+----------------------
 
-* success: performed action and everything went well
-* error: didnt work
-* warning: important notice
+An array of notification is passed to the templates, containing at least one of these:
+
+* success: an action was performed and everything went well.
+* error: something went wrong
+* warning: important notice the merchant should know about.
 * info: "just so you know"
 
+
 Display them
 ------------------------------
 
-Data are like:
-
-INCLUDE JSON
+Data are built this way:
 
+// TODO INCLUDE JSON
 
-In starter theme it looks like:
 
+In the Starter Theme, it looks like this:
 
 .. code-block:: smarty
 
@@ -74,18 +76,19 @@ In starter theme it looks like:
   </aside>
 
 
-Add message in your front controller
+Add your own message in your front controller
 --------------------------------------
 
-Your front controller holds the 4 following variables, they are arrays and they hold messages as string.
+Your front controller holds the 4 following variables.
 
 * $this->error
 * $this->success
 * $this->warning
 * $this->danger
 
+They are PHP arrays, and they hold messages as string.
 
-Since PrestaShop 1.7 you can redirect AND display a message after.
+Since PrestaShop 1.7, you can redirect AND display a message after an action.
 
 .. code-block:: php
 
diff --git a/themes/prologue/prologue.rst b/themes/prologue/prologue.rst
index adbc58819d..eaaf36b91a 100644
--- a/themes/prologue/prologue.rst
+++ b/themes/prologue/prologue.rst
@@ -2,77 +2,82 @@
 Prologue
 ********
 
-
-With PrestaShop 1.7 we have rebuild the theme system from the ground up. We had 2 goals
+With PrestaShop 1.7, we have rebuilt the theme system from the ground up. We had 2 goals
 in mind when doing this:
 
-* Make PrestaShop upgrade easier
-* Make it easy to integrate a new theme
+* Make PrestaShop upgrades easier,
+* Make it easy to create a new theme.
 
 
 
 Migrating from PrestaShop 1.6
 =============================
 
-This means that there is no easy way to migrate your front office form PrestaShop 1.6.
-When upgrading your store, your theme will be switch to the new default theme called "classic".
+The huge change to the theme system means that there is no easy way to migrate your current theme for PrestaShop 1.6 to PrestaShop 1.7.
+When upgrading your store, your theme will be switched to the new default theme, called "classic". We therefore advise you to work on your 1.7 theme before you make the switch to PS 1.7.
 
 
-Feature drop
+Dropped features
 --------------
 
-Some feature have been dropped with PrestaShop, here is a  list of the main ones (non-exhaustive)
+Some features have been dropped with PrestaShop 1.7. They were either already deprecated in 1.6, or proved too problematic to maintain.
 
 +---------+---------------------+
-| Feature | Reason              |
+| Feature | Reasons             |
 +---------+---------------------+
-| Live Edit | Live Edit will be replaced by a brand new theme editor in the next PrestaShop version|
+| Live Edit | Live Edit will be replaced by a brand new theme editor in the next PrestaShop version |
 +---------+---------------------+
-| Scenes | Scenes have been hidden and unsupported in PrestaShop 1.6, is is fully removed in PrestaShop 1.7 |
+| Scenes | Scenes have were alreadt hidden for new installes of PS 1.6, and were unsupported. There are now removed in PrestaShop 1.7. |
 +---------+---------------------+
-| Mobile theme | Within the last few year theme have gone responsive, there were no need for a mobile-specific theme anymore. Modules can still be disabled on a device basis. |
+| Mobile theme | In the last few years, webdesign have gone responsive. There is no need for a mobile-specific theme anymore: the way to go is responsive design. Note that modules can still be disabled on a device-type basis. |
 +---------+---------------------+
-| Map for store page | the default theme doesnt come with a map on the store page |
+| Map for store page | The default theme doesn't come with a map on the store page. |
 +---------+---------------------+
-| 5 steps checkout | There is no more choice between 5 step checkout or one page checkout. There is only one checkout, fully compatible with European laws. |
+| 5-step checkout | There is no more choice between 5-step checkout or one-page checkout (OPC). There is only one checkout, fully compatible with European laws. |
 +---------+---------------------+
 
 
 Coding standard and guidelines
 ------------------------------
 
-Intend with spaces for every language.
+General code guideline
+
+Intend with spaces for every language (PHP, HTML, CSS, etc.).
 
 See our .editorconfig for details
 http://editorconfig.org/
 
-PHP
-of course you follow PSR-1 et PSR-2
 
-HTML
+PHP files
+
+You should follow the PSR-2 standard, just like PrestaShop does.
+
+
+HTML file
+
+Use html 5: <br /> --> <br>, <section>, etc.
 
-use html 5: <br /> --> <br>, <section>,...
-all open tag must be closed in the same file (no div openned in header.tpl and closed in footer.tpl)
-subtemplates meant to be included must live inside a _partials folder
+All open tags must be closed in the same file (no div should be opened in header.tpl and closed in footer.tpl)
+Subtemplates (templates meant to be included in another template) must reside inside a /_partials/ folder.
 
 
-css
+CSS
 
-CSS3
-RSCSS http://rscss.io/
+Use CSS3.
+We recommand that you follow the RSCSS structure: http://rscss.io/
 
 
-JS
+JavaScript
 
-make sure your linter follows our .eslint
+Make sure your linter tool follows our .eslint file.
 ES6 -> babel
-split files and compile
+Split files and compile them.
 ES2015 standard https://babeljs.io/docs/learn-es2015/
 
 
-requirements
+Requirements
 -----------------
 
-php 5.4
+Your code should work on PHP 5.4+.
 
-Broswer supported for Bo and default theme classic
+// TODO Browser supported for BO and default theme
diff --git a/themes/smarty/smarty.rst b/themes/smarty/smarty.rst
index 39dfd753d8..ac31b560ab 100644
--- a/themes/smarty/smarty.rst
+++ b/themes/smarty/smarty.rst
@@ -4,27 +4,29 @@ Smarty
 
 
 [Note]
-Secyre by default. all html is escaped, use:
+With PrestaShop 1.7, we choose to be secure by default: all html is escaped, you do not have to explicitely escape variables anymore. See for instance:
 
 ..  code-block:: smarty
 
   {$variableWithHtml noscript}
 
+  
 Helpers and modifier
 ======================
 
 {url}
 ---------------
 
-PrestaShop 1.7 introduce a new smarty helper to generate urls here are some examples.
-This will take care of SSL, domain, virtual and physical base uri,  params concat and of course url rewritting.
-{url} use the Link class internatly
+PrestaShop 1.7 introduces a new Smarty helper to generate ULRs.
+This will take care of SSL, domain name, virtual and physical base URI, parameters concatenation, and of course URL rewritting.
 
-[NOTE] for link to any controller without params, please see `$urls` dataset.
+{url} uses the Link class internally.
 
+[NOTE] To link to any controller without params, please see the `$urls` dataset.
 
-[warning] an instance of link is still passed to the templates for retrocompat' purpose since it was heavily used.
-it is not recommended to use
+[WARNING] An instance of link is still passed to the templates for retrocompatibility purposes, since it was heavily used. It is not recommended to use it.
+
+Here is an example:
 
 .. code-block:: smarty
 
@@ -36,7 +38,7 @@ it is not recommended to use
 
   {url entity=address id=$id_address params=['delete' => 1]}
 
-will render (this is an example with my config, but you get the idea)
+...will render as:
 
 .. code-block:: html
 
@@ -53,12 +55,12 @@ Widgets
 {widget}
 ^^^^^^^^^
 
-PrestaShop 1.7  has introduce a new way to display modules. Instead of using a hook and hooking your module on it
-the widget function let you display any content from module in your template
+PrestaShop 1.7 introduces a new way to display modules. Instead of using a hook and hooking your module to it,
+the widget's function lets you display any content from the module in your template.
 
-[NOTE] link to full widget system doc
+// TODO link to full widget system doc
 
-If you want to displau the shop contact info using ps_contactinfo, you can write this
+For instance, if you want to display the shop's contact info from the  ps_contactinfo module, you can write this:
 
 .. code-block:: smarty
 
@@ -66,8 +68,7 @@ If you want to displau the shop contact info using ps_contactinfo, you can write
     {widget name="ps_contactinfo"}
   </div>
 
-since some module have different template depending on which hook they are hooked on, you
-can pass the hook name as well
+Since some module have different templates depending on which hook they are hooked on, you can pass the hook name as well:
 
 
 .. code-block:: smarty
@@ -80,10 +81,10 @@ can pass the hook name as well
 {widget_block}
 ^^^^^^^^^^^^^^^
 
-Even better you can rewrite the template on the go. the module will use your smarty code instead of loading
+Even better, you can rewrite the template on the go. The module will use your Smarty code instead of loading
 the template file.
 
-With ps_linklist example, instead of using `ps_linklist/ps_linklist/views/templates/hook/linkblock.tpl`, you can override it this way:
+Taking the ps_linklist module as an example, instead of using `ps_linklist/ps_linklist/views/templates/hook/linkblock.tpl`, you can override it this way:
 
 .. code-block:: smarty
 
@@ -104,7 +105,7 @@ With ps_linklist example, instead of using `ps_linklist/ps_linklist/views/templa
 {render}
 --------------
 
-ui as to come form controller. so far only used for forms (customer info and checkout).
+The interface elements (UI) have to come from the controller. So far, it is only used for forms (customer info and checkout).
 needs to implement `FormInterface`
 
 .. code-block:: smarty
@@ -115,7 +116,7 @@ needs to implement `FormInterface`
 {form_field}
 ^^^^^^^^^^^^^^
 
-
+Form fields are called this way:
 
 .. code-block:: Smarty
 
@@ -139,26 +140,28 @@ $field is an array like:
 Class name modifiers
 ------------------------
 
-in order to use data from controller to generate classnames we added these 2 modifiers
+In order to use the data from controller to generate classnames, we added 2 modifiers: 'classname' and 'classnames'.
 
 
 classname
 ^^^^^^^^^^
 
-classname will ensure your string is a valid class name. it will:
+The classname data modifier will ensure that your string is a valid class name. 
+
+It will:
 
-1. lowercase
-1. replace funny characters with latin non accented ones (see https://github.com/PrestaShop/PrestaShop/blob/develop/classes/Touls.php#L1297-L1393)
-1. replace all alphnumerical char by one dash
-1. ensure only one consecutive dash
+1. Put it in lowercase.
+2. Replace any funny characters with latin non accented ones.
+3. Replace all alphanumerical char by one dash.
+4. Ensure only one consecutive dash is used.
 
 
 classnames
 ^^^^^^^^^^
 
-takes an array, key is the classname and the value is a boolean indicating if it should be displayed or not.
+This data modifier takes an array, where the key is the classname and the value is a boolean indicating if it should be displayed or not.
 
-note that each class names are passed the classname filter
+Note that each classname is passed through the classname filter.
 
 .. code-block:: php
 
diff --git a/themes/templates/layouts.rst b/themes/templates/layouts.rst
index b3869dfa53..222bfe13f9 100644
--- a/themes/templates/layouts.rst
+++ b/themes/templates/layouts.rst
@@ -1,21 +1,21 @@
 ***************
-Templates
+Templates and layouts
 ***************
 
-All templates files lives in `templates/`.
-there is a functionnal split: checkout-related templates, customer-related templates,...
+PrestaShop themes are based on the Smarty template engine: http://www.smarty.net/v3_overview
 
-All files generate a whole page unless they are inside a `_partials` directry or subdir (see coding standard)
+All templates files live in the `templates/` folder.
+There is a functionnal split: there are checkout-related templates, customer-related templates, etc.
 
-PrestaShop themes are based on Smarty teplate engine http://www.smarty.net/v3_overview
+All files generate a whole HTML page, unless they are inside a `_partials` directry or subdirectory (see our coding standard).
 
 
 Templates inheritance
 ===========================
 
-Smarty 3.0 has a new inheritance feature
+Smarty 3.0 has a inheritance feature.
 
-example from smarty documentation
+Here is an example from the Smarty documentation:
 
 **parent.tpl**
 
@@ -40,15 +40,16 @@ example from smarty documentation
 
   {block name=body}My Child Body{/block}
 
-The output of child.tpl will be
+
+  The output of child.tpl will be:
 
 .. code-block:: html
 
   <html>
     <head>
-      <title>My Child Title<title>
+      <title>My Child.tpl Title<title>
     </head>
     <body>
-      My Child Body
+      My Child.tpl Body
     </body>
   </html>