Edited text.

Signed-off-by: MCamp859 <maryx.camp@intel.com>
This commit is contained in:
MCamp859
2019-01-11 11:51:42 -05:00
parent 88a09a22f6
commit 52a6071097
3 changed files with 100 additions and 84 deletions
@@ -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.