The title above is the title of the tutorial, corresponding to an <h1> in
HTML. It's the top-level link in the left navigation hierarchy. This paragraph
is an introduction to the tutorial. Tell the reader what this tutorial is for
and show him or her the end state of what you'll accomplish in this tutorial.
You can use multiple paragraphs if you want, of course, but get to the point as soon as possible. Note that for the entirety of the tutorial, all the Documentation Guidelines apply.
Second level headings are divided into major tasks. Your tutorial might have one or several major tasks, depending on its complexity. In the site, major tasks are in the left navigation at the second level, implemented using anchor tags to take the reader directly to the location of the heading in the tutorial.
In the body of your major task, you can use introductory/explanatory text, but the majority of the task should be in the form of numbered steps.
-
This is a numbered step. Describe here something specific the reader is supposed to do.
-
Here's another numbered step. It also should be something specific. There should be at least two numbered steps for every task. If you only have one, leave it as a paragraph.
When you're finished with numbered steps and are ready to go on to the next major task, briefly mention what you've done and what you're about to do in the next major task. This is called a segue.
Each major task has the same structure: introductory text, numbered steps, and summary text.
+$$$
You can also add Sidebars to the text if there's background information that's helpful, but doesn't necessary fit into the task at hand.
$$$
At the bottom of the tutorial, let the reader know some other topics that flow naturally from the tutorial he or she has just read. This gives developers various learning paths through the tutorials, in case they're spending some time exploring Liferay's technology.