doc/templates.md in power_stencil-0.4.6 vs doc/templates.md in power_stencil-0.4.7

@@ -17,19 +17,23 @@
 <!-- /TOC -->
 [:back:][Documentation root]
 
 # Templates overview
 
-Templates are the key feature of `PowerStencil` (hence the name). Templates are what will use the [entities] you carefully crafted in order to produce something during the [build][builds] process.
+Template is a key feature of `PowerStencil` (hence the name). In templates you define how you will use the [entities] you carefully crafted in order to produce something during a [build][builds] process.
 
-Currently the underlying engine is [ERB].
+The default templating engine being [ERB], your templates should be written using the [ERB] syntax, like most templates are written in the [Ruby On Rails] framework. This is basically some [Ruby] inside some ERB tags.
 
-When an entity type has some templates associated and you create an entity, it will create a directory `<entity_type>/<entity_name>` where you will fond those templates.
+Templates are always associated to some [buildable entities][buildable].
 
+When a [buildable entity][buildable] has some templates associated, they will be located in a directory `<entity_type>/<entity_name>/`. For some entity types, when you will create a new entity of this type, some default templates will be created in that directory (this is the case of the `simple_exec` entity type as you will see in the next paragraph). This is what is called `templates-templates`.
+
+In this document, you will learn how to create your own templates, as well as your own templates-templates.
+
 # Templates discovery with `simple_exec` entity type
 
-In the basic entity types, the only one having templates is the `simple_exec` entity type. So let's try with it:
+In the basic entity types, the only one providing default templates is the `simple_exec` entity type. So let's try with it:
 
 ```shell
 $ power_stencil create simple_exec/demo_templates 
 Created 'simple_exec/demo_templates'
 
@@ -39,13 +43,13 @@
   - Storage path   : '/tmp/tst3/.ps_project/entities/simple_exec/demo_templates.yaml'
   - Templates path : '/tmp/tst3/simple_exec/demo_templates'
   - Status         : Valid 
   - Buildable      : true
 ```
-As you can see the output of `power_stencil check` shows more information than entities we already created. First we see that this entity is `buildable`, and we'll detail that in the [builds] document, but for the moment what we will focus on the `Templates path` information.
+As you can see the output of `power_stencil check` shows more information than entities we created so far. First we see that this entity is `buildable`, and we'll detail that in the [builds] document, but for the moment what we will focus on the `Templates path` information.
 
-And it's true if we have a look in the `simple_exec/demo_templates` from the root of the project, a file appeared there:
+And it's true if we have a look in the `simple_exec/demo_templates/` directory from the root of the project, a file appeared there:
 
 ```shell
 $ ls -l simple_exec/demo_templates
 total 4
 -rwxrwxr-x 1 laurent laurent 57 août  23 16:44 main.sh
@@ -136,10 +140,10 @@
 Here are the main methods:
 
 - `entity(type, name)` will return any entity from the repository. The method is self-explanatory, this is the most generic way to access any entity of the repository.
 - `entities(criterion: nil, value: nil, &filter_block)` which is a more generic entities query method where `criterion` can be `:by_name` or `:by_type` and that will return an array (that you can potentially filter using the `filter_block`).
 - `build_target` will return the entity that you are currently building.
-- `project_config` is a shortcut to the project entity. You could actually retrieve it using the `entity(type, name)` method. 
+- `project_config` is a shortcut to the project entity. You could actually retrieve it using the `entity(:project_config, 'Project Config')` method.
 
 And of course you have access like in `power_stencil shell` to any class brought by `PowerStencil`, you could create entities there, destroy some, **but you should not do it**, as it would be very weird to do that during the process of detemplating !
 
 # Where do I create templates ?
 
\ No newline at end of file