6caf5be120
Added a section that discusses task, concept, and reference types of topics with examples. Change-Id: I66f363902287e1351b70fefbd3736dac0ba78fa0 Closes-Bug: #1521260
75 lines
2.6 KiB
ReStructuredText
75 lines
2.6 KiB
ReStructuredText
.. _topic_structure:
|
|
|
|
===============
|
|
Topic structure
|
|
===============
|
|
|
|
The OpenStack community welcomes all contributors to documentation. This
|
|
section provides recommendations on how to structure the content that you
|
|
submit to the ``openstack-manuals`` repository.
|
|
|
|
Organize technical information in topics. Use the principles of topic-based
|
|
authoring in all technical publications.
|
|
|
|
Topic-based authoring is an approach to the content creation where
|
|
you structure information in small chunks of a particular type. In contrast to
|
|
the book content, where information has a linear structure, in topic-based
|
|
authoring, you presume that a user can start reading documentation from
|
|
any topic. Therefore, each topic represents an independent piece of
|
|
information. Each topic states prerequisites and dependencies, if any, as
|
|
well as provides information about the next steps.
|
|
|
|
In topic-based authoring, a chunk of information is called `topic`.
|
|
|
|
Structure the information around the following topics:
|
|
|
|
**Concept**
|
|
A concept topic explains a particular functionality. A concept
|
|
topic does not provide a sequence of steps or information on how to use the
|
|
functionality.
|
|
|
|
Example of a concept topic title: *Introduction to the OpenStack components
|
|
and services*.
|
|
|
|
A concept topic includes:
|
|
|
|
* Title
|
|
* Description
|
|
* Related links
|
|
* (optional) Diagrams
|
|
* (optional) Examples
|
|
|
|
**Task**
|
|
A task topic explains how to complete a particular task and provides
|
|
a sequence of steps on how to achieve the goal of the task. A section
|
|
(or chapter) is the high level task topic.
|
|
|
|
Typically, a section includes multiple sub-sections: task, concept, and
|
|
reference topics. Start the title of a high level task topic with a verb
|
|
in gerund and the title of a subtask topics with a verb in imperative.
|
|
|
|
Task topics are the most important topics in any technical documentation.
|
|
Typically, the reader browses through the table of contents searching for
|
|
the information on how to configure the network, storage, or any other
|
|
component of a system.
|
|
|
|
Examples of the concept topic titles:
|
|
|
|
* Section topic title: *Monitoring performance*.
|
|
* Task topic title: *Delete a node*, *Recover from a failure*.
|
|
|
|
A task topic includes:
|
|
|
|
* Title
|
|
* Short description (intro)
|
|
* Procedure (a sequence of steps)
|
|
* Result
|
|
* Related links (See also)
|
|
* (optional) Examples
|
|
|
|
**Reference**
|
|
A reference topic provides additional information about a functionality.
|
|
Typically, information in a reference topic is presented in lists or tables.
|
|
|
|
Example of a reference topic title: *Supported operating systems*.
|