Following these writing guidelines will keep OSC documentation consistent and readable. Only a few areas are covered below, as we don’t want to make it too complex. You can’t go wrong keeping things simple and clear.

Don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to this guide than no information at all. OSC’ Documentation project team will be happy to help you with the prose.

General Guidelines for All Documents

Use standard American English and spelling
Use consistent terminology
Write in the active voice, using present simple tense when possible
Write objective, professional content
Keep sentences and paragraphs short and clear
Use a spell checker

Abbreviations and Acronyms

Write out the term the first time it appears in the document, immediately followed by the acronym or abbreviation in parentheses, i.e. ReStructuredText (RST). Then use the acronym in the rest of the document. In diagrams, if space allows, write out the full term. Use “an” before an acronym that begins with a vowel sound when spoken aloud; use “a” before an acronym that begins with a consonant sound when spoken aloud. Examples: an RST file, a PMML file.

GUI Elements

In general, write menu names as they appear in the UI. For example, if a menu or item name is all caps, then write it all caps in the document.

Headings (Titles)

Use brief, but specific, informative titles
Use capitalization; do not end with a period or colon
Use a gerund to begin section titles if it makes sense. Examples: Configuring, Managing, Starting
Use descriptive titles for tables and figures titles; do not number tables or figures; do not (in general) add titles for screen shots

Use the following to create the Document title:

= with overline/underline

Use the following symbols to create headings:

Section 1: * with overline/underline

Section 1.1: - with underline

Section 1.1.1: + with underline

Section 1.1.1.1: ^ with underline

Consider rewriting the content if your document needs more than 4 levels of headings.

Non-Numbered Headings in RST

Below is an example of how to denote headings of various levels in RST.

See the Section Headers Example - No Automatic Numbering for how this renders in HTML.

=================
H1 Document Title
=================

***************
Section 1 Title
***************

Section 1.1 Title
-----------------

Section 1.1.1 Title
+++++++++++++++++++

Section 1.1.1.1 Title
^^^^^^^^^^^^^^^^^^^^^

Section 1.1.1.1 Title2
^^^^^^^^^^^^^^^^^^^^^^

Another Section at the 1.1.1 Level
++++++++++++++++++++++++++++++++++

How the Header is Underlined Makes all the Difference
+++++++++++++++++++++++++++++++++++++++++++++++++++++

Section 1.2 Title
-----------------

Section 1.2.1 Title
+++++++++++++++++++

Section 1.2.2 Title
+++++++++++++++++++

***************
Section 2 Title
***************

***************
Section 3 Title
***************

Automatically Numbered Headings in RST

RST supports automatic numbering of sections. Place the sectnum directive at the top of your page. See the 1 Section Headers Example - Automatic Numbering for how this renders in HTML. Note that RST considers the Document Title to be the first Header and will number it!

=================
H1 Document Title
=================

.. sectnum::
***************
Section 1 Title
***************

Section 1.1 Title
-----------------

Section 1.1.1 Title
+++++++++++++++++++

Section 1.1.1.1 Title
^^^^^^^^^^^^^^^^^^^^^

Section 1.1.1.1 Title2
^^^^^^^^^^^^^^^^^^^^^^

Another Section at the 1.1.1 Level
++++++++++++++++++++++++++++++++++

How the Header is Underlined Makes all the Difference
+++++++++++++++++++++++++++++++++++++++++++++++++++++

Section 1.2 Title
-----------------

Section 1.2.1 Title
+++++++++++++++++++

Section 1.2.2 Title
+++++++++++++++++++

***************
Section 2 Title
***************

***************
Section 3 Title
***************

If your guide has enough content, consider breaking it up into chapters, with one chapter per RST file.