.. _detailed:

Detailed Writing Style Guidelines
#################################

Tone and audience
*****************

The tone of the |project|'s documentation should be clear, concise,
confident, and courteous. We are writing to peers, so we want to be
familiar. Use you, we and avoid the passive voice, but while remaining
professional. The writing should carry an undertone of cordiality,
respect, and cooperation.

Assume your audience is at about the same level of technical
understanding and expertise as you are. We don't want to talk down to
our readers. Do not assume the readers know everything about the
subject. Offer brief explanations or summaries of "common knowledge"
where you think a significant portion of readers might benefit.

.. toctree::
   :maxdepth: 2

   detailed_parallellism.rst
   detailed_simple.rst
   detailed_lists.rst
   detailed_notices.rst
   detailed_modular.rst