mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-08-29 14:33:48 +00:00
Rodrigo Caballero
131 lines
4.0 KiB
ReStructuredText
131 lines
4.0 KiB
ReStructuredText
.. _basic:
|
|
|
|
Basic contribution guide
|
|
########################
|
|
|
|
This list compiles the most common format, markup, structure, and grammar
|
|
rules for your convenience. You can find more detailed information in the
|
|
referenced sections.
|
|
|
|
.. contents::
|
|
:local:
|
|
:backlinks: entry
|
|
|
|
Format
|
|
******
|
|
|
|
* Limit line length to 78 characters. The GitHub web interface forces this
|
|
limitation for readability.
|
|
|
|
* Remove trailing white space from your documents.
|
|
|
|
* Use short sentences and paragraphs. Keep sentence length under 20 words.
|
|
|
|
* Use only lower case letters for filenames.
|
|
|
|
* Separate multiple words in filenames using dashes.
|
|
|
|
Markup
|
|
******
|
|
|
|
* Use the appropriate :abbr:`ReST (ReStructuredText)` roles for your content.
|
|
See the `ReST primer`_ for the complete list of roles.
|
|
|
|
* Use the :abbr: role to define the first instance of an abbreviation, for
|
|
example: :abbr:\`CL (Clear Linux)\`.
|
|
|
|
* Use hash-tags to underline the file's main title.
|
|
|
|
* Use asterisks to underline the file's first level headings.
|
|
|
|
* Use equal signs to underline the file's second level of headings.
|
|
|
|
* Use dashes to underline the file's third level of headings.
|
|
|
|
* Use labels to reference documentation sections. Do not reference
|
|
sections with URLs. See :ref:`cross` for details.
|
|
|
|
* Don't use explicit URLs as links, for example https://clearlinux.org/.
|
|
|
|
* Always include descriptive link text. For example:
|
|
Visit the `Clear Linux website`_. Do not use "here", "this", or similar
|
|
references for link text.
|
|
|
|
Structure
|
|
*********
|
|
|
|
* All files must have a main title and up to three levels of headings.
|
|
Restructure the content in multiple files as needed to comply.
|
|
|
|
* Use descriptive headings.
|
|
|
|
* Follow all headings with at least one paragraph of content. There should
|
|
never be two consecutive headings.
|
|
|
|
* Separate the link and the target definition. All target definitions must be
|
|
included at the end of the file. See :ref:`cross` for details.
|
|
|
|
* Use parallelism in headings, sentences, and lists. See our
|
|
:ref:`parallelism` for details.
|
|
|
|
* Put conditional phrases first in cautions and warnings. For example:
|
|
"If you do X, then Y will occur." See our :ref:`notices` guide.
|
|
|
|
* Place figures and tables immediately after related text.
|
|
|
|
* Place code or commands immediately after the leading text in a new line,
|
|
see our :ref:`code`.
|
|
|
|
* Reference figures, code examples, and tables by number.
|
|
For example, use "Figure 1," instead of "The figure above or below". See
|
|
:ref:`cross` and :ref:`images`.
|
|
|
|
* Include at least one direct reference to any table or figure you add. See
|
|
:ref:`tables`.
|
|
|
|
Grammar
|
|
*******
|
|
|
|
* Include only one main idea in a sentence. See :ref:`simple`.
|
|
|
|
* Limit the number of clauses you use to no more than two. See :ref:`simple`.
|
|
|
|
* Limit the number of sentences per paragraph to about six. See :ref:`simple`.
|
|
|
|
* Use strong verbs. See :ref:`simple`.
|
|
|
|
* Use action verbs. See :ref:`simple`.
|
|
|
|
* Avoid weak verbs like be, have, make, and do. See :ref:`simple`.
|
|
|
|
* Use short direct commands and avoid niceties such as the word
|
|
"please".
|
|
|
|
* Use the present tense wherever possible and avoid past and future
|
|
tense verbs. See :ref:`simple`.
|
|
|
|
* Use Active voice. Write, "Someone does something"; don't write,
|
|
"Something is done by someone" or "Something is done." See :ref:`simple`.
|
|
|
|
* Use "we" for recommendations. Write "We recommend..." as opposed to
|
|
"It is recommended...." See :ref:`simple`.
|
|
|
|
* Use "you" rather than "the user" in your instructions.
|
|
|
|
* Use short common English words whenever possible, see our :ref:`simple`
|
|
guide.
|
|
|
|
* Avoid contractions. See :ref:`grammar`.
|
|
|
|
* Use articles such as 'a', 'an', and 'the' to reduce ambiguity.
|
|
|
|
Additional information
|
|
**********************
|
|
|
|
Learn more about the accepted rules of grammar, punctuation, and word use in
|
|
our :ref:`language`. If you are looking for tips on how to write shorter,
|
|
clearer, and more concise content, visit our :ref:`simple` guide.
|
|
|
|
.. _Clear Linux website: https://clearlinux.org/
|
|
.. _ReST primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html
|