From 1924519636f1fdae7604511138d2b4b2764ae406 Mon Sep 17 00:00:00 2001 From: Lana Brindley Date: Mon, 26 Sep 2016 15:55:54 +1000 Subject: [PATCH] Updated Task section to reflect missing information In the original Style Guide wiki, we had guidance on colon use for procedure steps. This seems to have been lost in the transition to the current Contrib Guide. This patch adds it back in, based on the original wiki entry: https://wiki.openstack.org/w/index.php?title=Documentation%2FConventions&type=revision&diff=45083&oldid=45077 Change-Id: I5d36dd90c8c535588d7a5c61ece6ba8b004d90e0 --- .../source/topic-structure.rst | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/doc/contributor-guide/source/topic-structure.rst b/doc/contributor-guide/source/topic-structure.rst index 1ed2face63..a140e918e9 100644 --- a/doc/contributor-guide/source/topic-structure.rst +++ b/doc/contributor-guide/source/topic-structure.rst @@ -40,17 +40,12 @@ Structure the information around the following topics: * (optional) Examples **Task** - A task topic provides a sequence of steps detailing how to achieve a - certain 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 topic 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 - information on how to configure the network, storage, or any other - component of a system. + A task topic provides a sequence of steps (a procedure) detailing how to + achieve a particular outcome, such as configuring a network. If you have + conceptual information related to the task, put it into an overview before + the procedure. Make the steps in the procedure concise. Start each step in + a procedure with a verb. If the step includes a command example, end the + introductory sentence with a colon (:). Examples of concept topic titles: @@ -60,7 +55,7 @@ Structure the information around the following topics: A task topic includes: * Title - * Short description (intro) + * Short description (overview) * Procedure (a sequence of steps) * Result * Related links (See also)