Add structure section

source/3-tutorials/tutorial-guidelines.html.md

@@ -6,6 +6,61 @@ title: Tutorials Writing Guidelines
 
 ## Structure
 
+Conciseness, clarity and order are three of the key conditions that a tutorial should accomplish. To make sure that your tutorial meets these requirements, you need to create a strong and step-through structure before writing the tutorial. And keep the same structure in all the tutorials you produce in order to make your documentation consistent.
+
+Here is an example / template you can use as an inspiration to create your own tutorials structure:
+
+### Introduction
+
+The introduction should be a general overview of what the user can expect of the tutorial that it is about to read. It should contains, at least, the following content:
+
+  * A short definition about the product or topic covered by the tutorial.
+  * Provide some context about the use scenario of the product or topic of the tutorial.
+  * Specify the goal of the tutorial and the results that users will obtain following it.
+  * Mention what users will learn using the tutorial.
+  * Explain briefly how will be the processes explained: with an example application, using a specific tool, etc.
+
+### Assumptions and Prerequisites
+
+Depending of the complexity of the topic you will cover in the tutorial, you need to provide information about what users need to know and have installed in their systems before following the instructions to achieve successfully the goal of the tutorial.
+
+Add a list of knowledge assumptions and system requisites supplying links to learn the required topics or install the needed resources. Find below an example of a prerequisites list:
+
+> This guide makes the following assumptions:
+> * You have a Docker environment installed and configured. [Learn more about installing Docker](https://docs.docker.com/engine/installation/).
+> * You have a Docker Hub account. [Register for a free account](https://hub.docker.com/).
+> * You have a basic understanding of how containers work. Learn more about containers in [our YouTube video](https://www.youtube.com/watch?v=Pb1bgI59dF0), on [Wikipedia](https://en.wikipedia.org/wiki/Operating-system-level_virtualization) and on [ZDNet](http://www.zdnet.com/article/containers-fundamental-to-the-evolution-of-the-cloud/).
+
+### Overview steps (optional)
+
+To make easier a first contact with the flow that users will follow in the guide you can optionally add a subsection with the list of the steps / actions they will perform. These can be linkable so users can skip those steps that they have actually done.
+
+### Instructions
+
+It is very important to chunk the instructions in different steps or sections, that way, the tutorial is more readable and easy to follow.
+
+  * Title: the title of each step needs to be clear and concise, preferably written in active voice. It should describe accurately the action that is explained in the section.
+  * Instructions / Steps:
+    * Each content block or section should describe just one action. Write the actions in steps, shown as an ordered list. Never more than 8 steps in the same section. If the section needs more than 8 steps to achieve the goal, consider to split it in two sections.
+    * Place a sentence at the beginning of the section that resumes the goal of the current step and how it will be explained. Then, proceed with the instructions creating different steps.
+
+### Caveats
+
+A good way to warn users about expected errors or known issues they may find following the tutorial is to write a "caveat" section at the end of the tutorial. It is a good way to clarify some points shown in the tutorial and help users to understand and solve them by themselves. [Check this Algolia's caveats section to have a live example](https://www.algolia.com/doc/tutorials/indexing/3rd-party-service/firebase-algolia/?language=swift#caveats).
+
+### Resources
+
+Point users to both external useful resources and internal documentation references that may be useful to understand and deepen the concepts they just learn in the tutorial. These resources can be:
+
+  * Links to official documentation.
+  * Links to internal related tutorials and how-to guides.
+  * Links to Git Hub repositories.
+  * Links to blog posts.
+  * Links to use cases.
+  * Demos and video tutorials.
+
+In the same line, you also can include a **What's next** section which includes links to more advanced tutorials that help to complete the product user journey.
+
 ## General writing guidelines
 
 ## Assumptions, Prerequisites & Knowledge level