From patchwork Sat Oct 8 13:18:01 2016 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stephen Finucane X-Patchwork-Id: 679899 X-Patchwork-Delegate: rbryant@redhat.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from archives.nicira.com (archives.nicira.com [96.126.127.54]) by ozlabs.org (Postfix) with ESMTP id 3srn7B6s9Qz9s5g for ; Sun, 9 Oct 2016 00:20:06 +1100 (AEDT) Authentication-Results: ozlabs.org; dkim=fail reason="key not found in DNS" (0-bit key; unprotected) header.d=that.guru header.i=@that.guru header.b=CB4At6xW; dkim-atps=neutral Received: from archives.nicira.com (localhost [127.0.0.1]) by archives.nicira.com (Postfix) with ESMTP id 0AB7D10A03; Sat, 8 Oct 2016 06:20:06 -0700 (PDT) X-Original-To: dev@openvswitch.org Delivered-To: dev@openvswitch.org Received: from mx1e3.cudamail.com (mx1.cudamail.com [69.90.118.67]) by archives.nicira.com (Postfix) with ESMTPS id 1F13A109DD for ; Sat, 8 Oct 2016 06:20:04 -0700 (PDT) Received: from bar5.cudamail.com (localhost [127.0.0.1]) by mx1e3.cudamail.com (Postfix) with ESMTPS id 8DFC34207CB for ; Sat, 8 Oct 2016 07:20:03 -0600 (MDT) X-ASG-Debug-ID: 1475932802-09eadd70ff09940001-byXFYA Received: from mx3-pf3.cudamail.com ([192.168.14.3]) by bar5.cudamail.com with ESMTP id lFDtCaaabHodOval (version=TLSv1 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO) for ; Sat, 08 Oct 2016 07:20:02 -0600 (MDT) X-Barracuda-Envelope-From: stephen@that.guru X-Barracuda-RBL-Trusted-Forwarder: 192.168.14.3 Received: from unknown (HELO bumble.birch.relay.mailchannels.net) (23.83.209.25) by mx3-pf3.cudamail.com with ESMTPS (DHE-RSA-AES256-SHA encrypted); 8 Oct 2016 13:18:13 -0000 Received-SPF: none (mx3-pf3.cudamail.com: domain at that.guru does not designate permitted sender hosts) X-Barracuda-Apparent-Source-IP: 23.83.209.25 X-Barracuda-RBL-IP: 23.83.209.25 X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from relay.mailchannels.net (localhost [127.0.0.1]) by relay.mailchannels.net (Postfix) with ESMTP id 439C4E027C for ; Sat, 8 Oct 2016 13:18:12 +0000 (UTC) Received: from one.mxroute.com (ip-10-220-3-24.us-west-2.compute.internal [10.220.3.24]) by relay.mailchannels.net (Postfix) with ESMTPA id 84974E06F8 for ; Sat, 8 Oct 2016 13:18:11 +0000 (UTC) X-Sender-Id: mxroute|x-authuser|stephen@that.guru Received: from one.mxroute.com ([UNAVAILABLE]. [10.28.138.177]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384) by 0.0.0.0:2500 (trex/5.7.8); Sat, 08 Oct 2016 13:18:12 +0000 X-MC-Relay: Neutral X-MailChannels-SenderId: mxroute|x-authuser|stephen@that.guru X-MailChannels-Auth-Id: mxroute X-MC-Loop-Signature: 1475932691768:4141702172 X-MC-Ingress-Time: 1475932691767 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=that.guru; s=default; h=References:In-Reply-To:Message-Id:Date:Subject:Cc:To:From: Sender:Reply-To:MIME-Version:Content-Type:Content-Transfer-Encoding: Content-ID:Content-Description:Resent-Date:Resent-From:Resent-Sender: Resent-To:Resent-Cc:Resent-Message-ID:List-Id:List-Help:List-Unsubscribe: List-Subscribe:List-Post:List-Owner:List-Archive; bh=j2s3K3AsFAxgNtYUItaACxjNl9hxB9kmAGQwedWT4jM=; b=CB4At6xW8t40e/DSY/cbour/Ot PZLsx7SC+MXgLQYBIyYgns4sB/XUAvaXDK2RWXhxmyz3XwHPID2JM6v9o/J4AAx4IzAzD0EfvHgUA OMaBmN7QYmiRZFHCWyKwuBZVTgNSuf57zS0Tydf1vmVNm3NUxrRbHDsGzt/9N6U3dZfMtZsJVnM2k La1OJ9F3Tu+qnUXguFtNGwbrSy3uCaPW6t2ltwmXZ8a8GiaDtAuH2aPITpFNYmOT1Oa8L9X4Ps9K8 2BQoKnOFXd6LOugxMcnPe7spXXpCx1KX05byPyor54vfIZzXTCTbHWJJevfpotxXEwVzYzVs2RW+n WyzIQgeg==; X-CudaMail-Envelope-Sender: stephen@that.guru From: Stephen Finucane To: dev@openvswitch.org X-CudaMail-MID: CM-V3-1007005301 X-CudaMail-DTE: 100816 X-CudaMail-Originating-IP: 23.83.209.25 Date: Sat, 8 Oct 2016 14:18:01 +0100 X-ASG-Orig-Subj: [##CM-V3-1007005301##][PATCH 2/2] docs: Add writing guide Message-Id: <1475932681-17056-2-git-send-email-stephen@that.guru> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1475932681-17056-1-git-send-email-stephen@that.guru> References: <1475932681-17056-1-git-send-email-stephen@that.guru> X-AuthUser: stephen@that.guru X-GBUdb-Analysis: 0, 23.83.209.25, Ugly c=0.335748 p=-0.0769231 Source Normal X-MessageSniffer-Rules: 0-0-0-11571-c X-Barracuda-Connect: UNKNOWN[192.168.14.3] X-Barracuda-Start-Time: 1475932802 X-Barracuda-Encrypted: DHE-RSA-AES256-SHA X-Barracuda-URL: https://web.cudamail.com:443/cgi-mod/mark.cgi X-Virus-Scanned: by bsmtpd at cudamail.com X-Barracuda-BRTS-Status: 1 X-Barracuda-Spam-Score: 1.20 X-Barracuda-Spam-Status: No, SCORE=1.20 using global scores of TAG_LEVEL=3.5 QUARANTINE_LEVEL=1000.0 KILL_LEVEL=4.0 tests=BSF_SC0_MV0713, BSF_SC0_SA085, BSF_SC5_MJ1963, DKIM_SIGNED, RDNS_NONE X-Barracuda-Spam-Report: Code version 3.2, rules version 3.2.3.33574 Rule breakdown below pts rule name description ---- ---------------------- -------------------------------------------------- 0.00 DKIM_SIGNED Domain Keys Identified Mail: message has a signature 0.10 RDNS_NONE Delivered to trusted network by a host with no rDNS 0.10 BSF_SC0_SA085 Custom Rule SA085 0.50 BSF_SC0_MV0713 Custom rule MV0713 0.50 BSF_SC5_MJ1963 Custom Rule MJ1963 Subject: [ovs-dev] [PATCH 2/2] docs: Add writing guide X-BeenThere: dev@openvswitch.org X-Mailman-Version: 2.1.16 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: dev-bounces@openvswitch.org Sender: "dev" Help documentation authors avoid common pitfalls. Signed-off-by: Stephen Finucane --- 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 `__. @@ -83,7 +86,7 @@ guide `__. 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:: `` 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:: ``) 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 +`__. + +- 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 ------------