diff -r 98a84761634f -r 7e69ecc9fd43 src/source/dev_guide/howto-portlet.rst
--- a/src/source/dev_guide/howto-portlet.rst	Fri Dec 14 12:16:12 2018 +0100
+++ b/src/source/dev_guide/howto-portlet.rst	Mon Dec 17 17:19:35 2018 +0100
@@ -17,12 +17,45 @@
 :ref:`pyams_content`.
 
 
-1. Define portlet settings
-''''''''''''''''''''''''''
+Create Portlet
+---------------
+
+The Portlet component is a utility, which implements the :py:class:`pyams_portal.interfaces.IPortlet` interface and is
+registered by the :py:func:`pyams_portal.portlet.portlet_config` decorator;
+
+.. code-block:: python
+
+    @portlet_config(permission=VIEW_PERMISSION)
+    class ImagePortlet(Portlet):
+        """Image portlet"""
+
+        name = NEW_PORTLET_NAME
+        label = _("New portlet")
+
+        toolbar_image = None
+        toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o'
+
+
+Where:
+ - **permission**: permission required to display this portlet content
+ - **name**: internal name given to this portlet. This name must be unique between all portlets, so using your own
+   namespace into this name is generally a good option!
+ - **label**: user label given to this portlet
+ - **toolbar_image**: URL of an image used to display portlet button into ZMI toolbar, if any
+ - **toolbar_css_class**: CSS class used to display portlet button into ZMI toolbar, if any
+
+NB: the argument **settings_class** could be set to add a portlet settings (see below).
+
+
+Portlet settings
+----------------
 
 Portlet settings interface are defined in ``interfaces.py``, you can use :py:class:`pyams_portal.interfaces.IPortletSettings`
 or extend the interface by adding additional properties for example:
 
+1) create portlet settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. code-block:: python
 
     from zope.schema import Text
@@ -46,11 +79,10 @@
         comment = FieldProperty(INewPortletSettings['comment'])
 
 
-2. Create Portlet
-'''''''''''''''''
+2. declare the settings portlet
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The Portlet component is a utility, which implements the :py:class:`pyams_portal.interfaces.IPortlet` interface and is
-registered by the :py:func:`pyams_portal.portlet.portlet_config` decorator;
+Add the settings portlet class inside the portlet
 
 .. code-block:: python
 
@@ -63,24 +95,14 @@
 
         toolbar_image = None
         toolbar_css_class = 'fa fa-fw fa-2x fa-picture-o'
-
         settings_class = NewPortletSettings
 
 
-Where:
- - **permission**: permission required to display this portlet content
- - **name**: internal name given to this portlet. This name must be unique between all portlets, so using your own
-   namespace into this name is generally a good option!
- - **label**: user label given to this portlet
- - **toolbar_image**: URL of an image used to display portlet button into ZMI toolbar, if any
- - **toolbar_css_class**: CSS class used to display portlet button into ZMI toolbar, if any
- - **settings_class**: class used to store portlet settings.
 
+3. portlet settings edit form
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-3. Create portlet settings edit form
-''''''''''''''''''''''''''''''''''''
-
-Portlet settings have to be updated through management interface via a :py:class:`pyams_portal.zmi.portlet.PortletSettingsEditor`
+Portlet settings have to be updated through management interface (ZMI) via a :py:class:`pyams_portal.zmi.portlet.PortletSettingsEditor`
 subform:
 
 .. code-block:: python
@@ -98,8 +120,8 @@
         """New portlet settings editor, JSON renderer"""
 
 
-4. Previewing portlet content
-'''''''''''''''''''''''''''''
+Previewing portlet content
+--------------------------
 
 A *previewer* is used into ZMI to display portlet content into portal template definition page:
 
@@ -132,8 +154,8 @@
 Here we check if portlet is visible or not to display a small icon when hidden; otherwise we display entered comment.
 
 
-5. Rendering portlet content
-''''''''''''''''''''''''''''
+Rendering portlet content
+-------------------------
 
 A *renderer* is used to display portlet content into rendered page content: