From 414dd6ccd5ffbe974ba4349a3fbebafc6313d0fe Mon Sep 17 00:00:00 2001
From: Linette <stemke@us.ibm.com>
Date: Tue, 17 Nov 2015 11:10:57 -0600
Subject: [PATCH] [Contributor Guide] Enhance writing style section

Added 3 new sections to writing style section -
avoid ambiguous titles, use consistent terms,
use spelling tools when available. These sections
can help improve SEO results for content.

Change-Id: I0c83efc00529135028e2c560fbd7c19df9453787
Closes-Bug: #1513270
---
 .../general-writing-guidelines.rst            | 51 +++++++++++++++++--
 1 file changed, 48 insertions(+), 3 deletions(-)

diff --git a/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst b/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst
index 5363179555..ddccf67676 100644
--- a/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst
+++ b/doc/contributor-guide/source/writing-style/general-writing-guidelines.rst
@@ -196,10 +196,26 @@ Keep sentences short
 
 Short and simple sentences are easier to read and understand.
 
-Follow the principles of minimalism
------------------------------------
+Avoid ambiguous titles
+----------------------
 
-If you can describe an idea in one word, do not use two words.
+Each title should include a clear description of the page’s subject.
+
++-------------------------+------------------------+
+| **Ambiguous**           | **Better**             |
++=========================+========================+
+| Update metadata         | Update flavor metadata |
++-------------------------+------------------------+
+
+Also, ensure that you follow the documentation guidelines for titles.
+For more information,
+see http://docs.openstack.org/contributor-guide/rst-conv/titles.html.
+
+Be clear and concise
+--------------------
+
+Follow the principles of minimalism. If you can describe
+an idea in one word, do not use two words.
 Eliminate all redundant modifiers, such as adjectives and adverbs.
 
 Write objectively
@@ -346,3 +362,32 @@ Eliminate needless politeness
 -----------------------------
 
 Do not use "please" and "thank you" in technical documentation.
+
+Use consistent terminology
+--------------------------
+
+Use consistent terms across OpenStack content. Avoid multiple
+variations or spellings to refer to the same service, function,
+UI element, and so on.
+
+**Example of usage**
+
++------------------------+----------------------------------+
+| **Do not use**         | **Use**                          |
++========================+==================================+
+| Firewall as a service  | Firewall-as-a-Service            |
++------------------------+----------------------------------+
+| active-active          | active/active                    |
++------------------------+----------------------------------+
+| module                 | service                          |
++------------------------+----------------------------------+
+
+If you suspect the subject was previously described, search the
+OpenStack documentation and look for a precedence.
+
+Use spelling and grammar checking tools
+---------------------------------------
+
+Run text through spelling and grammar checking tools, if available.
+Correcting mistakes, especially to larger sections of new content,
+helps eliminate rework later.