Rewording for setup-env.rst, starter-theme.rst and theme-organization.rst.

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

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/

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

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
 

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');