Document Structure

Structuring the Document

Tutorials and How-tos

In the introduction, provide basic information about the tutorial:

• What the reader will do (e.g. deploy an Edge cluster from an OpenNebula Front-end)
• What the reader will achieve (e.g. a working Edge cluster ready for testing)
• Approximately how long it should take to do

Ideally, tutorials should include only a single pathway for the reader to follow. Thus in a tutorial we can include the main high-level steps near the top of the document, for example:

To install an OpenNebula Front-end using miniONE, we’ll need to complete the following high-level steps:

1. Prepare the AWS VM where we’ll install miniONE.
2. Update the OS in the VM.
3. Download and run the miniONE script.
4. Verify the installation.

In the document itself, if possible try to make the subsection headings coincide with, or reference, the high-level steps. For instance, for the above example the title of the first section might be “Step 1: Prepare the VM in AWS.”

In the above example, the high-level steps divide the document into four parts. In the document itself (whether tutorial or how-to), it’s good practice to reinforce each of these parts by following this basic structure:

1. At the beginning, briefly state the goal of the high-level step (even if being redundant).
2. List and describe the actions required (optionally you can divide them into substeps, e.g. 1.1, 1.2 etc.)
3. At the end, describe the result, e.g. “At this point, the OpenNebula Front-end should be up and running”.

In other words, for each part reinforce the goal and the outcome.

Explanation

At or near the beginning of the document, state the scope of the document as briefly and clearly as possible, e.g. “This page provides a high-level overview of the OpenNebula cloud model, architecture and components.” Optionally specify if the document addresses a more specific need.

If possible, structure the document so it explains high-level concepts first, then gradually goes into lower-level explanation. However, include as little technical description as possible, instead providing links to reference documentation.

When writing, try to determine if the reader could benefit from a definition of the subject, or of individual elements in the doc. A definition is not an example, nor a statement of what something does, but a statement of what something is; it expresses the essential nature of something. Don’t hesitate to include definitions of external components if necessary, for example “Ansible is a Python application for IT automation. It can deploy software, configure systems [etc.],” or “The OpenNebula OneFlow API is a RESTful service used to create, control and monitor services [etc.].”

Reference

Reference documents are not intended to be read sequentially but to be consulted, as when you consult a dictionary.

A reference document is the final, authoritative source for information within the documentation. In IT, the authority of a reference document is derived from the source code itself.

A reference document focuses on description, but can include definitions and short examples.

It does not try to explain, but to describe and sometimes to define.

Ideally it should maintain a standard format throughout the document, like a dictionary. To achieve this, it may be useful to structure the information in tables or predefined paragraph styles.

Reference documents should be complete. The reader should know that the document is the most complete description of its subject. A good example in the OpenNebula docs is the Virtual Machines States Reference. At the beginning it states that it is a complete reference, and links to other docs where the reader may find simplified explanations of its subject. It then uses a standardized format (a table) to list all VM states and provide an explanation for each.