[ovs-dev] [PATCH 2/2] docs: Add writing guide

Stephen Finucane stephen at that.guru
Sat Oct 8 13:18:01 UTC 2016


Help documentation authors avoid common pitfalls.

Signed-off-by: Stephen Finucane <stephen at that.guru>
---
I imagine this could be contentious, which is why I included it
separately :)
---
 DocumentationStyle.rst | 92 +++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 80 insertions(+), 12 deletions(-)

diff --git a/DocumentationStyle.rst b/DocumentationStyle.rst
index d37f3c0..10271eb 100644
--- a/DocumentationStyle.rst
+++ b/DocumentationStyle.rst
@@ -39,8 +39,11 @@ generator.  Sphinx introduces a number of extensions to reST, like the
 not work correctly on GitHub. As such, these extensions should not be used in
 any documentation in the root level, such as the ``README``.
 
+reST Conventions
+----------------
+
 Basics
-------
+~~~~~~
 
 Many of the basic documentation guidelines match those of the `coding style
 guide <CodingStyle.md>`__.
@@ -83,7 +86,7 @@ guide <CodingStyle.md>`__.
   changes! Docs aren't unit testable, so visible inspection is necessary.
 
 File Names
-----------
+~~~~~~~~~~
 
 - Use hyphens as space delimiters. For example: ``my-readme-document.rst``
 
@@ -94,7 +97,7 @@ File Names
     project.
 
 Titles
-------
+~~~~~~
 
 - Use the following headers levels.
 
@@ -115,7 +118,7 @@ Titles
 - Use "title case" for headers.
 
 Code
-----
+~~~~
 
 - Use ``::``, the ``code`` role or the ``code-block:: <syntax>`` role to prefix
   code.
@@ -126,7 +129,7 @@ Code
   pre-requisites, explain what they are and how to achieve them.
 
 Admonitions
------------
+~~~~~~~~~~~
 
 - Use admonitions to call attention to important information.::
 
@@ -137,13 +140,15 @@ Admonitions
   Example admonitions include: ``warning``, ``important``, ``note``, ``tip`` or
   ``seealso``.
 
+- Use notes sparingly. Avoid having more than one per subsection.
+
 Tables
-------
+~~~~~~
 
 - Use either graphic tables, list tables or CSV tables.
 
 Graphic tables
-~~~~~~~~~~~~~~
+++++++++++++++
 
 ::
 
@@ -175,7 +180,7 @@ Graphic tables
   The ``table`` role (`` .. table:: <name>``) can be safely omitted.
 
 List tables
-~~~~~~~~~~~
++++++++++++
 
 ::
 
@@ -193,7 +198,7 @@ List tables
          - 2.6.18 to 3.2
 
 CSV tables
-~~~~~~~~~~
+++++++++++
 
 ::
 
@@ -206,7 +211,7 @@ CSV tables
        1.6.x, 2.6.18 to 3.2
 
 Cross-referencing
------------------
+~~~~~~~~~~~~~~~~~
 
 - To link to an external file or document, include as a link.::
 
@@ -251,7 +256,7 @@ Cross-referencing
     This is a Sphinx extension. Do not use this in any top-level documents.
 
 Figures and Other Media
------------------------
+~~~~~~~~~~~~~~~~~~~~~~~
 
 - All images should be in ASCII format and included in code-blocks to preserve
   formatting.
@@ -259,13 +264,76 @@ Figures and Other Media
 - Include other reStructuredText verbatim in a current document
 
 Comments
---------
+~~~~~~~~
 
 - Comments are indicated by means of the ``..`` marker.::
 
       .. TODO(stephenfin) This section needs some work. This TODO will not
          appear in the final generated document, however.
 
+Writing Style
+-------------
+
+Follow these guidelines to ensure readability and consistency of the Open
+vSwitch documentation. These guidelines are based on the `IBM Style Guide
+<http://www.redbooks.ibm.com/Redbooks.nsf/ibmpressisbn/9780132101301?Open>`__.
+
+- Use standard US English
+
+  Use a spelling and grammar checking tool as necessary.
+
+- Expand initialisms and acronyms on first usage.
+
+  Commonly used terms like CPU or RAM are allowed.
+
+  .. list-table:: Example
+     :header-rows: 1
+
+     * - Do not use
+       - Do use
+     * - OVS is a virtual switch. OVS has...
+       - Open vSwitch (OVS) is a virtual switch. OVS has...
+     * - The VTEP emulator is...
+       - The Virtual Tunnel Endpoint (VTEP) emulator is...
+
+- Write in the active voice
+
+  The subject should do the verb's action, rather than be acted upon.
+
+  .. list-table:: Example
+     :header-rows: 1
+
+     * - Do not use
+       - Do use
+     * - A bridge is created by you
+       - Create a bridge
+
+- Write in the present tense
+
+  .. list-table:: Example
+     :header-rows: 1
+
+     * - Do not use
+       - Do use
+     * - Once the bridge is created, you can create a port
+       - Once the bridge is created, create a port
+
+- Write in second person
+
+  .. list-table:: Example
+     :header-rows: 1
+
+     * - Do not use
+       - Do use
+     * - To create a bridge, the user runs:
+       - To create a bridge, run:
+
+- Keep sentences short and consise
+
+- Eliminate needless politeness
+
+  Avoid "please" and "thank you"
+
 Useful Links
 ------------
 
-- 
2.7.4




More information about the dev mailing list