From 6caf5be12089e89283b3027f62d3f5e113e0d47b Mon Sep 17 00:00:00 2001
From: Svetlana Karslioglu <skarslioglu@mirantis.com>
Date: Mon, 14 Sep 2015 13:37:19 -0700
Subject: [PATCH] Added a section about topic-based authoring

Added a section that discusses task, concept, and reference
types of topics with examples.

Change-Id: I66f363902287e1351b70fefbd3736dac0ba78fa0
Closes-Bug: #1521260
---
 doc/contributor-guide/source/index.rst        |  2 +-
 .../source/topic-structure.rst                | 74 +++++++++++++++++++
 2 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 doc/contributor-guide/source/topic-structure.rst

diff --git a/doc/contributor-guide/source/index.rst b/doc/contributor-guide/source/index.rst
index b1bb4c5022..0554e36e4b 100644
--- a/doc/contributor-guide/source/index.rst
+++ b/doc/contributor-guide/source/index.rst
@@ -19,6 +19,7 @@ Contents
    first-timers-quickstart.rst
    additional-git-workflow.rst
    writing-style.rst
+   topic-structure.rst
    rst-conv.rst
    docbook-conv.rst
    docs-structure.rst
@@ -30,7 +31,6 @@ Contents
    build-locally.rst
    blueprints-and-specs.rst
    json-conventions.rst
-
    common/glossary.rst
 
 Search in this guide
diff --git a/doc/contributor-guide/source/topic-structure.rst b/doc/contributor-guide/source/topic-structure.rst
new file mode 100644
index 0000000000..9008da8e85
--- /dev/null
+++ b/doc/contributor-guide/source/topic-structure.rst
@@ -0,0 +1,74 @@
+.. _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*.