29 lines
846 B
ReStructuredText
29 lines
846 B
ReStructuredText
.. _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
|
|
|
|
simple
|
|
steps
|
|
parallelism
|
|
lists
|
|
notices
|
|
modular |