wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

notes on doc style

Browse source
This commit is contained in:
Richard van der Hoff 2018-02-06 16:09:53 +00:00
parent 91c1d9ed58
commit 306783b7bf
1 changed files with 35 additions and 2 deletions
Download patch file Download diff file Expand all files Collapse all files

37
meta/documentation_style.rst
View file

@ -1,8 +1,9 @@
Documentation Style
===================
A brief single sentence to describe what this file contains; in this case a
description of the style to write documentation in.
Each document should begin with aa brief single sentence to describe what this
file contains; in this case a description of the style to write documentation
in.
Format
------
@ -49,3 +50,35 @@ Line widths
We use 80 characters for line widths. This is a guideline and can be flouted IF
AND ONLY IF it makes reading more legible. Use common sense.
Stylistic notes
---------------
General
~~~~~~~
Try to write clearly and unambiguously. Remember that many readers will not
have English as their first language.
Prefer British English (colour, -ise) to American English.
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."
* ``description``: a longer description of the behaviour of this API, written
in complete sentences.
* ``operationId``: a camelCased unique identifier for this endpoint. This will
be used to automatically generate bindings for the endpoint.
* Parameter and property ``description``\s: a phrase summarising the behaviour
of this parameter or property, optionally followed by sentences giving more
detailed explanations.
The description is also the place to define default values for optional
properties. Use the wording "Defaults to X [if unspecified]."