From 1028ea355881486b9701eed80c6d0501aeabfdb7 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Tue, 6 Feb 2018 17:30:22 +0000 Subject: [PATCH] doc style: lists --- meta/documentation_style.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/meta/documentation_style.rst b/meta/documentation_style.rst index 9729b867..8ee530c0 100644 --- a/meta/documentation_style.rst +++ b/meta/documentation_style.rst @@ -62,13 +62,19 @@ have English as their first language. Prefer British English (colour, -ise) to American English. +Lists should: + +* Be introduced with a colon. +* Be used where they provide clarity. +* Contain entries which start with a capital and end with a full stop. + OpenAPI ~~~~~~~ When writing OpenAPI specifications for the API endpoints, follow these rules: * ``summary``: a phrase summarising what this API does. Start with a capital, - end with a full-stop. Examples: "Sends an event."; "Searches the directory." + end with a full stop. Examples: "Sends an event."; "Searches the directory." * ``description``: a longer description of the behaviour of this API, written in complete sentences. @@ -78,7 +84,7 @@ When writing OpenAPI specifications for the API endpoints, follow these rules: * Parameter and property ``description``\s: a phrase summarising the behaviour of this parameter or property, optionally followed by sentences giving more - detailed explanations. + detailed explanations. Start with a capital, end with a full stop. The description is also the place to define default values for optional properties. Use the wording "Defaults to X [if unspecified]."