
:LastChangedDate: $LastChangedDate$
:LastChangedRevision: $LastChangedRevision$
:LastChangedBy: $LastChangedBy$

Twisted Writing Standard
========================

The Twisted writing standard describes the documentation writing
styles we prefer in our narrative documentation.

This standard applies particularly to howtos and other descriptive documentation.
For writing API documentation, please refer to :doc:`Docstrings section in our coding standard <coding-standard>`.

This document is meant to help Twisted documentation authors produce
documentation that does not have the following problems:

- misleads users about what is good Twisted style;
- misleads users into thinking that an advanced howto is an introduction
  to writing their first Twisted server; and
- misleads users about whether they fit the document's target audience:
  for example, that they are able to use enterprise without knowing how to
  write SQL queries.


General style
-------------

Documents should aim to be clear and concise, allowing the API
documentation and the example code to tell as much of the story as they
can. Demonstrations and where necessary supported arguments should always
preferred to simple statements ("here is how you would simplify this
code with Deferreds" rather than "Deferreds make code
simpler").

Documents should be clearly delineated into sections and subsections.
Each of these sections, like the overall document, should have a single
clear purpose. This is most easily tested by trying to have meaningful
headings: a section which is headed by "More details" or
"Advanced stuff" is not purposeful enough. There should be
fairly obvious ways to split a document. The two most common are task
based sectioning and sectioning which follows module and class
separations.

Documentation must use American English spelling, and where possible
avoid any local variants of either vocabulary or grammar. Grammatically
complex sentences should ideally be avoided: these make reading
unnecessarily difficult, particularly for non-native speakers.

When referring to a hypothetical person, (such as "a user of a website written with twisted.web"), gender neutral pronouns (they/their/them) should be used.

For reStructuredText documents which are handled by the Sphinx documentation generator make lines short, and break lines at natural places, such as after commas and semicolons, rather than after the 79th column.
We call this *semantic newlines*.
This rule **does not** apply to docstrings.

..  code-block:: text
    :linenos:

    Sometime                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             