mirror of
https://github.com/clearlinux/clear-linux-documentation.git
synced 2026-11-22 03:22:45 +00:00
@@ -8,29 +8,29 @@ be improved? Help us out by contributing! If you haven't contributed before,
|
||||
take a moment to review our `Contribution guidelines`_.
|
||||
|
||||
Do you have questions about contributing to the documentation that were not
|
||||
answered by our guidelines? Send your question to the `mailing list`_ at: dev@lists.clearlinux.org.
|
||||
answered by these guidelines? Send your question to the `mailing list`_ at:
|
||||
dev@lists.clearlinux.org.
|
||||
|
||||
Contribution guidelines
|
||||
***********************
|
||||
|
||||
We welcome all contributions to our documentation. For all contributions,
|
||||
please follow our guidelines for consistent, readable documentation.
|
||||
We welcome contributions and we ask you to follow our guidelines for
|
||||
consistent, readable documentation.
|
||||
|
||||
For new content, it is important to understand how Sphinx works and how the
|
||||
documentation is organized and structured.
|
||||
The |CL| documentation is hosted in GitHub and is written using
|
||||
reStructuredText. These guidelines provide examples, templates, and best
|
||||
practices for your contributions.
|
||||
|
||||
Before contributing
|
||||
===================
|
||||
|
||||
If you haven't contributed before, take the time to get familiar with the existing
|
||||
documentation and organization (link). Make sure you are familiar with our writing and
|
||||
formatting guidelines, as well as basic reStructuredText and Sphinx:
|
||||
If you haven't contributed before, review the following items:
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
writing-guide
|
||||
structure-formatting
|
||||
* GitHub `documentation repository`_ shows our document organization.
|
||||
* :ref:`writing-guide` describes the style we use to keep our documents clear
|
||||
and concise.
|
||||
* :ref:`structure-formatting` provides details on how we use reStructuredText
|
||||
and Sphinx in our documents.
|
||||
|
||||
How to contribute
|
||||
=================
|
||||
|
||||
@@ -4,30 +4,32 @@ Structure and formatting
|
||||
########################
|
||||
|
||||
Content should be organized to support scanning. Consistent organization,
|
||||
formatting, and writing style helps readers quickly find what they need and
|
||||
to understand the content more effectively.
|
||||
|
||||
Use the organization and formatting guidelines described in this document with
|
||||
the 'writing-guide'_ to create scannable content.
|
||||
formatting, and writing style helps readers quickly find what they need and to
|
||||
understand the content more effectively. This document describes our
|
||||
organization and formatting guidelines.
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 1
|
||||
|
||||
Refer to :ref:`writing-guide` to learn how we keep our documents clear and
|
||||
concise.
|
||||
|
||||
|
||||
Markup
|
||||
******
|
||||
|
||||
Documentation is written using the reStructuredText markup language,
|
||||
with extensive use of Sphinx roles and directives. We use Sphinx to generate
|
||||
the final documentation. You can read more about reStructuredText and Sphinx
|
||||
on their respective websites:
|
||||
Our documentation is written in the reStructuredText markup language, using
|
||||
Sphinx roles and directives. We use Sphinx to generate the final
|
||||
documentation. You can read more about reStructuredText and Sphinx on their
|
||||
respective websites:
|
||||
|
||||
* `Sphinx documentation`_
|
||||
* `reStructuredText Primer`_
|
||||
|
||||
You can view the content directly in the .rst markup files, or install and run
|
||||
the documentation locally, in order to generate the HTML content. To run the
|
||||
documentation locally, follow the instructions found in the `documentation repository`_
|
||||
README.
|
||||
You can view the content directly in the .rst markup files, or you can
|
||||
generate the HTML content by installing and running the documentation locally.
|
||||
To run the documentation locally, follow the instructions found in the
|
||||
`documentation repository`_ README.
|
||||
|
||||
New pages
|
||||
=========
|
||||
@@ -51,8 +53,8 @@ For example, the "Documentation contribution guidelines" page toctree looks like
|
||||
writing-guide
|
||||
structure-formatting
|
||||
|
||||
Additionally, each page should include a uniquely named reST label directly
|
||||
before the page title, to enable the use of the `Sphinx ref role`_ for linking to a page.
|
||||
Additionally, each page must include a uniquely named reST label directly
|
||||
before the page title, to enable the `Sphinx ref role`_ for linking to a page.
|
||||
|
||||
For example, this page "Structure and formating" has the label ``.. _structure-formatting``:
|
||||
|
||||
@@ -86,8 +88,8 @@ Page structure
|
||||
|
||||
Each page in the documentation should follow the basic format of:
|
||||
|
||||
* Overview: 1-2 sentences describing what this page will show and why it matters
|
||||
* Prerequisites: Describe any pre work necessary to the content (if appropriate)
|
||||
* Overview: 1-2 sentences describing what this page shows and why it matters
|
||||
* Prerequisites: Describe any pre-work necessary to the content (if appropriate)
|
||||
* Content
|
||||
* Next steps: List links to next steps (if appropriate)
|
||||
* Related topics: List links to related content (if appropriate)
|
||||
@@ -98,9 +100,9 @@ Headings
|
||||
Use headings to section and organize your content for better readability and
|
||||
clarity.
|
||||
|
||||
* All files must have a top level heading, which will be the title for the page.
|
||||
* All files must have a top level heading, which is the title for the page.
|
||||
* Headings should be short and descriptive.
|
||||
* Headings must be written in sentence case.
|
||||
* Write headings in sentence case (capitalize only the first word and proper nouns).
|
||||
* Up to three additional levels of headings are allowed under the title heading.
|
||||
* Each heading must be followed by at least one paragraph of content. There
|
||||
should never be two consecutive headings.
|
||||
@@ -147,14 +149,14 @@ Inline text formatting
|
||||
**********************
|
||||
|
||||
We use the `Microsoft Writing Style Guide`_ as our starting point for text
|
||||
formatting, and execute the formatting using reST and Sphinx markup.
|
||||
formatting. We execute the formatting using reST and Sphinx markup.
|
||||
|
||||
Use our quick reference for the most commonly used inline text elements:
|
||||
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| **Element** | **Convention** | **reST/Sphinx** |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Emphasis | Italic. | ``*strong*`` |
|
||||
| Emphasis | Italic | ``*strong*`` |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Tool names | Correctly capitalized, no quotes, | |
|
||||
| | bold, or italics as the basic rule. | |
|
||||
@@ -163,13 +165,13 @@ Use our quick reference for the most commonly used inline text elements:
|
||||
| | name is the command, treat it like | |
|
||||
| | a command. | |
|
||||
| | | |
|
||||
| | If the tool name is lower case and | |
|
||||
| | If the tool name is lowercase and | |
|
||||
| | used at the start of a sentence, use | |
|
||||
| | bold. | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Commands | Bold. | Use the ``:command:`` role |
|
||||
| Commands | Bold | Use the ``:command:`` role. |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Command flags | Bold. | Use the ``:command:`` role |
|
||||
| Command flags | Bold | Use the ``:command:`` role. |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| New terms | Italic for first use, normal for all | ``*term*`` |
|
||||
| | subsequent use. | |
|
||||
@@ -177,11 +179,11 @@ Use our quick reference for the most commonly used inline text elements:
|
||||
| | If it is used outside of the source | |
|
||||
| | of definition, link the term. | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Bundle names | Bold. | Use the ``:command:`` role |
|
||||
| Bundle names | Bold | Use the ``:command:`` role. |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| File names, directories, paths | Title style capitalization | Use the ``:file:`` role |
|
||||
| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| File extensions | lowercase | |
|
||||
| File extensions | Lowercase | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Example URLs (not linked) | Plain text | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
@@ -198,7 +200,7 @@ Use our quick reference for the most commonly used inline text elements:
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Acronyms | Spell out first use, with | Use ``:abbr:`` |
|
||||
| | acronym in parenthesis. | |
|
||||
| | For all subsequent use, | |
|
||||
| | For all subsequent uses, | |
|
||||
| | use the acronym. | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Keystrokes | | Use ``:kbd:`` |
|
||||
@@ -212,7 +214,7 @@ Use our quick reference for the most commonly used inline text elements:
|
||||
| Local navigation | | ``.. contents:: :local:`` |
|
||||
| | | with a depth of 1 |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Environment variables | Use the casing of the | Use ``:envvar:`` |
|
||||
| Environment variables | Use the case format of the | Use ``:envvar:`` |
|
||||
| | environment variable. | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
| Inline comments | | Use ``..`` |
|
||||
@@ -222,7 +224,7 @@ Use our quick reference for the most commonly used inline text elements:
|
||||
| parts | e.g. <package-name>. | |
|
||||
| | | |
|
||||
| | Use square brackets for optional | |
|
||||
| | parts | |
|
||||
| | parts, | |
|
||||
| | e.g. [--build]. | |
|
||||
+--------------------------------+---------------------------------------+-----------------------------+
|
||||
|
||||
@@ -253,12 +255,11 @@ Lists and instructions
|
||||
**********************
|
||||
|
||||
Use a numbered list when the order or priority of the items is important, such
|
||||
as when writing instructions.
|
||||
as step-by-step instructions.
|
||||
|
||||
Use a bulleted list when the order of the items is not important.
|
||||
|
||||
For both kinds of list, strive to keep all items in the list parallel.
|
||||
Use sentence style, making all the list items sentences. See :ref:`parallelism`.
|
||||
For both list types, keep all items in the list parallel. See :ref:`parallelism`.
|
||||
|
||||
Use standard `reST list markup`_.
|
||||
|
||||
@@ -270,14 +271,14 @@ to show sequence for the items. Follow our guidelines for numbered lists:
|
||||
|
||||
* Make sure the list is sequential and not just a collection of items.
|
||||
* Introduce a numbered list with a sentence. End the setup text with a
|
||||
colon. Example: "To configure the unit, do the following: "
|
||||
colon. Example: "To configure the unit, perform the following steps:"
|
||||
* Each item in the list should be parallel.
|
||||
* Treat numbered list items as full sentences with correct ending
|
||||
punctuation.
|
||||
* You may interrupt numbered lists with other content, if relevant,
|
||||
e.g. explanatory text, commands, or code.
|
||||
* Second-level steps are acceptable; Avoid third-level steps.
|
||||
* Avoid single-step procedures; The minimum number of steps in a procedure
|
||||
* Second-level steps are acceptable; avoid third-level steps.
|
||||
* Avoid single-step procedures; the minimum number of steps in a procedure
|
||||
is two.
|
||||
* Do not create numbered lists that emulate flowcharts. The reader should be
|
||||
able to execute the list of steps from first to last without branching or
|
||||
@@ -292,12 +293,12 @@ Use bulleted lists to reduce wordiness and paragraph density, especially when
|
||||
a sequence is not required. Here are some guidelines for bulleted lists:
|
||||
|
||||
* Introduce a bulleted list with a sentence. End the setup text with a
|
||||
colon. Example: "To repair the unit, you will need the following: "
|
||||
colon. Example: "To repair the unit, you will need the following items:"
|
||||
* Each item in the list should be parallel.
|
||||
* Avoid interrupting bulleted lists with other paragraph styles.
|
||||
* Second-level bullets are acceptable; avoid third-level bullets.
|
||||
|
||||
If using sentence style bullet lists, use correct ending punctuation. For
|
||||
Use the correct ending punctuation for sentence style bullet lists. For
|
||||
example:
|
||||
|
||||
**Incorrect**
|
||||
@@ -316,8 +317,7 @@ example:
|
||||
|
||||
* Use a number that has a meaning for you.
|
||||
* Change the code once a month.
|
||||
* Do not disclose the user code to anyone else. This includes the security
|
||||
company.
|
||||
* Do not disclose the user code to anyone, including the security company.
|
||||
|
||||
Instructions
|
||||
============
|
||||
@@ -396,21 +396,29 @@ Links
|
||||
|
||||
Use the standard `reST markup for links`_.
|
||||
|
||||
External links use named reference in the text, referring to a defined link/label
|
||||
To add a link to another documentation page, use the `:ref:` role:
|
||||
|
||||
.. code-block:: rest
|
||||
|
||||
:ref:`structure-formatting`
|
||||
|
||||
To add an external link, we use named references that refer to a defined link/label
|
||||
at the bottom of the page.
|
||||
|
||||
For example, a link is defined at the bottom of the page:
|
||||
For example, a link is defined at the bottom of the page like this:
|
||||
|
||||
.. code-block:: rest
|
||||
|
||||
.. _wiki about dogs: https://en.wikipedia.org/wiki/Dog
|
||||
|
||||
And used in the content:
|
||||
The same link is used in the content like this:
|
||||
|
||||
.. code-block:: rest
|
||||
|
||||
Check out the great `wiki about dogs`_.
|
||||
|
||||
|
||||
|
||||
Images
|
||||
******
|
||||
|
||||
@@ -420,8 +428,8 @@ explain a topic or example.
|
||||
|
||||
Follow these guidelines when using graphics in support of your documentation:
|
||||
|
||||
* Keep it simple. Only use images that serve a specific purpose in your document,
|
||||
and the image should contain only the information the reader needs.
|
||||
* Keep it simple. Use images that serve a specific purpose in your document,
|
||||
and contain only the information the reader needs.
|
||||
|
||||
* Avoid graphics that will need frequent updating. Don't include information in
|
||||
a graphic that might change with each release, such as product versions.
|
||||
|
||||
@@ -7,16 +7,24 @@ We want our documentation to be easy to read and understand. This
|
||||
document describes guidelines for writing documentation that is
|
||||
clear, concise, confident, and courteous.
|
||||
|
||||
Refer to :ref:`structure-formatting` for details on how we use reStructuredText
|
||||
and Sphinx in our documents.
|
||||
|
||||
This document contains the following sections:
|
||||
|
||||
|
||||
.. contents:: :local:
|
||||
:depth: 1
|
||||
|
||||
|
||||
|
||||
Use simple English
|
||||
******************
|
||||
|
||||
Write using simple English: Be brief, get to the point, communicate only
|
||||
the information that is needed. Be friendly and informative. Emphasize
|
||||
clarity and avoid unnecessarily complicated or technical terms. Make the
|
||||
content accessible to non-native speakers.
|
||||
Write using simple English: Be brief and communicate only the information that
|
||||
is needed. Be friendly and informative. Emphasize clarity and avoid
|
||||
complicated or technical terms. Make the content accessible to non-native
|
||||
speakers.
|
||||
|
||||
Be brief
|
||||
========
|
||||
@@ -62,7 +70,7 @@ Follow our tips for making good word choices:
|
||||
more than in excess of
|
||||
if in the event of
|
||||
before prior to
|
||||
if you want should you wish
|
||||
if you want should one wish
|
||||
use utilize
|
||||
example instance
|
||||
=================== ===================
|
||||
@@ -70,9 +78,9 @@ Follow our tips for making good word choices:
|
||||
Avoid overuse of product name
|
||||
=============================
|
||||
|
||||
Use product name only when necessary. Many sentences can be re-written
|
||||
to not use the product name with no change in meaning. This keeps the
|
||||
content concise and scannable.
|
||||
Use product names only when necessary. Typically, you can rewrite sentences to
|
||||
remove the product name with no change in meaning, which keeps the content
|
||||
concise and scannable.
|
||||
|
||||
Avoid using the product name in page titles and headings. Keep page
|
||||
titles and headings concise and descriptive of the topic.
|
||||
@@ -81,7 +89,7 @@ Make content scannable
|
||||
**********************
|
||||
|
||||
Organize your content to make it scannable for the reader, which
|
||||
helps them find what the need quickly, and helps them understand more
|
||||
helps them find what they need quickly, and helps them understand more
|
||||
efficiently.
|
||||
|
||||
* **Put the most important content first.** Make sure your introduction
|
||||
@@ -99,7 +107,7 @@ Link text
|
||||
|
||||
All links in content should follow these guidelines:
|
||||
|
||||
* **Use descriptive link text**: Link text should describe where the
|
||||
* **Write descriptive link text**: Link text should describe where the
|
||||
link goes, without having to read the surrounding text.
|
||||
* **Keep link text concise**: Use only the words needed to accurately
|
||||
describe the destination.
|
||||
@@ -107,7 +115,7 @@ All links in content should follow these guidelines:
|
||||
see the same link text twice on a page, they'll assume it goes to the
|
||||
same place.
|
||||
* **Start link text with keywords**: Frontload the link text with the most
|
||||
important words - this helps users scan the text.
|
||||
important words to help users scan the text.
|
||||
* **Avoid generic text**: Don't use generic, uninformative link text such
|
||||
as "click here" or "read more".
|
||||
|
||||
@@ -139,9 +147,9 @@ For example:
|
||||
Use present tense
|
||||
=================
|
||||
|
||||
Use simple present tense instead of future tense for most text. Future
|
||||
tense is acceptable for conditional statements, for example in a caution
|
||||
or a warning.
|
||||
Use simple present tense instead of future tense for most text. Search for the
|
||||
words "will" or "shall" to find future tense instances. Future tense is
|
||||
acceptable for conditional statements, for example, in a caution or a warning.
|
||||
|
||||
For example:
|
||||
|
||||
@@ -197,9 +205,9 @@ Use active voice whenever possible to show who or what is performing an
|
||||
action.
|
||||
|
||||
* Active voice follows standard English word order: SUBJECT–VERB–OBJECT
|
||||
(optional).
|
||||
(where the OBJECT is optional).
|
||||
* Passive voice reverses the order and weakens the verb: OBJECT–be VERB–by
|
||||
SUBJECT (optional).
|
||||
SUBJECT (where the OBJECT is optional).
|
||||
|
||||
For example:
|
||||
|
||||
@@ -216,7 +224,7 @@ Or:
|
||||
Avoid long noun phrases
|
||||
***********************
|
||||
|
||||
Noun phrases - a noun and everything that describe or modify it - can be
|
||||
Noun phrases (a noun and other words that describe or modify it) can be
|
||||
difficult to understand. Try to limit the number of modifiers in a noun phrase
|
||||
to two.
|
||||
|
||||
@@ -265,7 +273,7 @@ structures and how they can be made parallel with a little rewording.
|
||||
Grammar and punctuation
|
||||
***********************
|
||||
|
||||
This section covers common grammatical topics relevant to the our
|
||||
This section covers common grammatical topics relevant to our
|
||||
documentation. For detailed explanations of correct grammar and punctuation,
|
||||
use one of our :ref:`preferred references <references>`.
|
||||
|
||||
@@ -295,7 +303,7 @@ A few other tips when referring to menu items:
|
||||
:menuselection:`View --> Side Bar --> Hide Side Bar`"
|
||||
|
||||
* Do not include more than 3 navigation steps in a menu selection. If
|
||||
more than three steps are needed divide the steps using
|
||||
more than three steps are needed, divide the steps using
|
||||
``:guilabel:`` or ``:menuselection:``.
|
||||
|
||||
For example: "Go to :guilabel:`File` and select
|
||||
@@ -305,11 +313,11 @@ Software version capitalization
|
||||
-------------------------------
|
||||
|
||||
When listing software or hardware version numbers, the word “version” or letter
|
||||
v are lowercase. The v is closed with the number (no period).
|
||||
"v" are lowercase. The v is closed with the number (no period).
|
||||
|
||||
For example:
|
||||
|
||||
* Widget Pro v5.0
|
||||
* Widget Pro version 5.0
|
||||
* Widget Master v2.1.12
|
||||
|
||||
Terms using a hyphen or slash
|
||||
@@ -326,8 +334,8 @@ For example:
|
||||
Contractions
|
||||
============
|
||||
|
||||
Avoid the use of contractions as they may not be clear to non-native
|
||||
English-speaking audiences.
|
||||
Avoid using contractions, such as it's, they're, and you're, because they may be
|
||||
unclear to non-native English-speaking audiences.
|
||||
|
||||
Quotation marks
|
||||
===============
|
||||
@@ -342,8 +350,8 @@ Commas and colons
|
||||
=================
|
||||
|
||||
This section addresses common use of commas, semicolons, and colons in our
|
||||
documentation. Refer to Merriam-Webster's Collegiate Dictionary or one of
|
||||
our :ref:`preferred references <references>` for further detail.
|
||||
documentation. Refer to one of our :ref:`preferred references <references>`
|
||||
for further details.
|
||||
|
||||
Use the serial comma
|
||||
--------------------
|
||||
@@ -374,7 +382,7 @@ For example:
|
||||
|
||||
* This is a capitalization example: Donuts do not cause holes.
|
||||
|
||||
* These is a non capitalization example: colons, semicolons, and commas.
|
||||
* These is a non-capitalization example: colons, semicolons, and commas.
|
||||
|
||||
Use a colon at the end of a sentence or phrase that introduces examples, a list,
|
||||
a path, user input, or code.
|
||||
|
||||
Reference in New Issue
Block a user