Next round revisions:

- alphabetize formatting table
- readd toctree to landing page, with alternate text
- line-length clean up
- add links to references available online
- misc cleanup

Signed-off-by: Kristal Dale <kristal.dale@intel.com>
This commit is contained in:
Kristal Dale
2019-01-11 13:52:33 -08:00
parent 52a6071097
commit 0855e8ed8d
3 changed files with 196 additions and 257 deletions
@@ -1,49 +1,43 @@
.. _collaboration:
Documentation contribution guidelines
#####################################
Documentation guidelines
########################
See a missing topic in the documentation? Find an existing document that could
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 these guidelines? Send your question to the `mailing list`_ at:
Do you have questions about the documentation that were not answered by these
guidelines? Send your question to the `mailing list`_ at:
dev@lists.clearlinux.org.
Contribution guidelines
***********************
We welcome contributions and we ask you to follow our guidelines for
consistent, readable documentation.
The |CL| documentation is hosted in GitHub and is written using
reStructuredText. These guidelines provide examples, templates, and best
practices for your contributions.
reStructuredText. Use our guidelines and best practices to write consistent,
readable documentation.
Before contributing
===================
.. toctree::
:maxdepth: 1
If you haven't contributed before, review the following items:
* 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.
Writing guide describes the style we use to keep our documents clear and concise. <writing-guide>
Structure and formatting guide details how we structure and format our documents using reStructuredText and Sphinx. <structure-formatting>
GitHub documentation repository shows our document organization. <https://github.com/clearlinux/clear-linux-documentation>
How to contribute
=================
*****************
There are multiple ways to contribute and help improve our documentation:
* **Make a suggestion**: Have a documentation suggestion but no time to write it
yourself? Send your suggestion to the `mailing list`_ at: dev@lists.clearlinux.org.
* **Log an issue**: If you find a problem in our documentation (such as typos or out-of-date
information), log an issue in the `documentation repository`_.
yourself? Send your suggestion to the `mailing list`_ at:
dev@lists.clearlinux.org.
* **Log an issue**: If you find a problem in our documentation (such as typos or
out-of-date information), log an issue in the `documentation repository`_.
* **Contribute directly via GitHub**: Whether you've found a typo, have better
instructions or examples, or have a new page to add, submit your improvement or
addition as a pull request on the `documentation repository`_.
instructions or examples, or have a new page to add, submit your improvement
or addition as a pull request on the `documentation repository`_.
* **Test documentation**: Step through our instructional guides and tutorials to
verify the instructions. Log or correct any out-of-date information.
@@ -74,17 +68,19 @@ Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_:
References
**********
We use the following references to guide the grammar, style, and formatting of our
documentation:
We use the following references to guide the grammar, style, and formatting of
our documentation:
* `Microsoft Writing Style Guide`_
* `Merriam-Webster Dictionary`_
* The Chicago Manual of Style (15th edition), The University of Chicago Press
* Merriam-Webster Dictionary
* Microsoft Manual of Style for Technical Publications, Microsoft Press
* Microsoft Press Computer Dictionary, Microsoft Press
* Read Me First!, Oracle Technical Publications
* The Merriam-Webster's Collegiate Dictionary
.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/
@@ -8,42 +8,41 @@ 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.
.. contents:: :local:
:depth: 1
Markup
******
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 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 you can
generate the HTML content by installing and running the documentation locally.
To run the documentation locally, follow the instructions found in the
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
=========
There are a few additional steps to consider when adding a new page to the
documentation. First, identify where your new page should be located within
the existing `Documentation organization`_. Second, make sure the new page
is picked up in the Sphinx build and easily linkable from other content.
documentation. First, identify where your new page should be located within the
existing `Documentation organization`_. Second, make sure the new page is picked
up in the Sphinx build and easily linkable from other content.
Each page must be included in a `Sphinx toctree`_ in order to
be included in the documentation content tree. Typically, pages are added to
the section landing page toctree.
Each page must be included in a `Sphinx toctree`_ in order to be included in the
documentation content tree. Typically, pages are added to the section landing
page toctree.
For example, the "Documentation contribution guidelines" page toctree looks like:
For example, the :ref:`collaboration` page toctree looks like:
.. code-block:: rest
@@ -53,10 +52,11 @@ For example, the "Documentation contribution guidelines" page toctree looks like
writing-guide
structure-formatting
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.
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``:
For example, this page "Structure and formating" has the label
``.. _structure-formatting``:
.. code-block:: rest
@@ -65,8 +65,8 @@ For example, this page "Structure and formating" has the label ``.. _structure-f
Structure and formatting
########################
This page can then be referenced from other pages in the documentation using
the `:ref:` role:
This page can then be referenced from other pages in the documentation using the
`:ref:` role:
.. code-block:: rest
@@ -77,7 +77,8 @@ Documentation organization
The documentation is organized into five general sections:
#. **Concepts**: Introduction and overview of |CL| specific concepts or features.
#. **Concepts**: Introduction and overview of |CL| specific concepts or
features.
#. **Get started**: Information about getting started with |CL|.
#. **Guides**: Detailed information and instruction on using |CL| features.
#. **Tutorials**: Step-by-step instruction for using |CL| in specific use cases.
@@ -102,7 +103,8 @@ clarity.
* All files must have a top level heading, which is the title for the page.
* Headings should be short and descriptive.
* Write headings in sentence case (capitalize only the first word and proper nouns).
* 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.
@@ -140,8 +142,8 @@ To mark up headings in the .rst file:
In-page navigation
==================
If a page has three or more sections, provide quick links to each section.
Place the quick links after the overview section.
If a page has three or more sections, provide quick links to each section. Place
the quick links after the overview section.
Use the standard `reST contents directive`_ with depth: 1 for quick links.
@@ -149,15 +151,73 @@ Inline text formatting
**********************
We use the `Microsoft Writing Style Guide`_ as our starting point for text
formatting. We execute the formatting using reST and Sphinx markup.
formatting. We apply the formatting using reST and Sphinx markup.
Use our quick reference for the most commonly used inline text elements:
+--------------------------------+---------------------------------------+-----------------------------+
| **Element** | **Convention** | **reST/Sphinx** |
+--------------------------------+---------------------------------------+-----------------------------+
| Acronyms | Spell out first use, with | Use ``:abbr:`` |
| | acronym in parenthesis. | |
| | For all subsequent uses, | |
| | use the acronym. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Bundle names | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Callouts | | Use ``.. note::`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` |
| | from rest of text. Use an | with the correct language |
| | indented call-out box. | setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Commands | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Command flags | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Console output | Monospace, visual distinction | Use ``.. code-block::`` |
| | from rest of text. Use an | with console as the |
| | indented call-out box. | language setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Emphasis | Italic | ``*strong*`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Environment variables | Use the case format of the | Use ``:envvar:`` |
| | environment variable. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example commands with | Use angle brackets for swapping | |
| optional or replaceable | in the specific name, | |
| parts | e.g. <package-name>. | |
| | | |
| | Use square brackets for optional | |
| | parts, | |
| | e.g. [--build]. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example URLs (not linked) | Plain text | |
+--------------------------------+---------------------------------------+-----------------------------+
| File extensions | Lowercase | |
+--------------------------------+---------------------------------------+-----------------------------+
| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| GUI labels | | Use ``:guilabel:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Inline comments | | Use ``..`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Keystrokes | | Use ``:kbd:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Local navigation | | ``.. contents:: :local:`` |
| | | with a depth of 1 |
+--------------------------------+---------------------------------------+-----------------------------+
| Menu selection | | Use ``:menuselection:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| New terms | Italic for first use, normal for all | ``*term*`` |
| | subsequent use. | |
| | | |
| | If it is used outside of the source | |
| | of definition, link the term. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Product name | Follow correct trademark and | |
| | attribution guidelines. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Tool names | Correctly capitalized, no quotes, | |
| | bold, or italics as the basic rule. | |
| | | |
@@ -169,64 +229,6 @@ Use our quick reference for the most commonly used inline text elements:
| | used at the start of a sentence, use | |
| | bold. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Commands | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Command flags | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| New terms | Italic for first use, normal for all | ``*term*`` |
| | subsequent use. | |
| | | |
| | If it is used outside of the source | |
| | of definition, link the term. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Bundle names | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| File extensions | Lowercase | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example URLs (not linked) | Plain text | |
+--------------------------------+---------------------------------------+-----------------------------+
| Product name | Follow correct trademark and | |
| | attribution guidelines. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` |
| | from rest of text. Use an | with the correct language |
| | indented call-out box. | setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Console output | Monospace, visual distinction | Use ``.. code-block::`` |
| | from rest of text. Use an | with console as the |
| | indented call-out box. | language setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Acronyms | Spell out first use, with | Use ``:abbr:`` |
| | acronym in parenthesis. | |
| | For all subsequent uses, | |
| | use the acronym. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Keystrokes | | Use ``:kbd:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| GUI labels | | Use ``:guilabel:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Menu selection | | Use ``:menuselection:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Callouts | | Use ``.. note::`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Local navigation | | ``.. contents:: :local:`` |
| | | with a depth of 1 |
+--------------------------------+---------------------------------------+-----------------------------+
| Environment variables | Use the case format of the | Use ``:envvar:`` |
| | environment variable. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Inline comments | | Use ``..`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Example commands with | Use angle brackets for swapping | |
| optional or replaceable | in the specific name, | |
| parts | e.g. <package-name>. | |
| | | |
| | Use square brackets for optional | |
| | parts, | |
| | e.g. [--build]. | |
+--------------------------------+---------------------------------------+-----------------------------+
White space and line length
===========================
@@ -239,9 +241,9 @@ Remove trailing whitespace from your documents.
Code blocks and examples
************************
When providing example code or commands that are less than 10 lines, use
the `Sphinx code-block directive`_. Use the appropriate syntax highlighting
for the example command or code.
When providing example code or commands that are less than 10 lines, use the
`Sphinx code-block directive`_. Use the appropriate syntax highlighting for the
example command or code.
For example, if showing console output, use console highlighting:
@@ -259,15 +261,16 @@ as step-by-step instructions.
Use a bulleted list when the order of the items is not important.
For both list types, keep all items in the list parallel. See :ref:`parallelism`.
For both list types, keep all items in the list parallel. See
:ref:`parallelism`.
Use standard `reST list markup`_.
Numbered lists
==============
Numbered lists are most frequently used for procedures. Use numbered lists
to show sequence for the items. Follow our guidelines for numbered lists:
Numbered lists are most frequently used for procedures. Use numbered lists 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
@@ -298,20 +301,9 @@ a sequence is not required. Here are some guidelines for bulleted lists:
* Avoid interrupting bulleted lists with other paragraph styles.
* Second-level bullets are acceptable; avoid third-level bullets.
Use the correct ending punctuation for sentence style bullet lists. For
example:
Use the correct ending punctuation for sentence style bullet lists. For example:
**Incorrect**
When setting the user code remember:
* make the user code easy to remember. 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
**Correct**
**Use this:**
When setting the user code, remember:
@@ -319,11 +311,20 @@ example:
* Change the code once a month.
* Do not disclose the user code to anyone, including the security company.
**Not this:**
When setting the user code remember:
* make the user code easy to remember. 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
Instructions
============
When presenting instructions, such as in a tutorial, present them in a
numbered list according to these guidelines:
When presenting instructions, such as in a tutorial, present them in a numbered
list according to these guidelines:
* Each step (list item) should describe one action.
@@ -346,79 +347,67 @@ numbered list according to these guidelines:
Notices
*******
We use four special types of notices: notes, cautions, warnings, and
dangers. Here are some specific rules and tips regarding use of these
notices:
We use four special types of notices: notes, cautions, warnings, and dangers.
Here are some specific rules and tips regarding use of these notices:
* Do not use a notice directly after a heading. Notices must follow a
variant of body text.
* Do not use a notice directly after a heading. Notices must follow a variant of
body text.
* Do not include more than one notice in a single notice block.
* Avoid back-to-back notices.
* If back-to-back notices are not avoidable, make sure each distinct
notice in the notice block is clearly defined.
* If back-to-back notices are not avoidable, make sure each distinct notice in
the notice block is clearly defined.
Use the standard `reST admonition directive`_.
Notes, cautions, warnings, and dangers
======================================
Notes, cautions, and warnings
=============================
Use notes sparingly. Avoid having more than one note per section. If
you exceed this number consistently, consider rewriting the notes as
main body text.
Use notes sparingly. Avoid having more than one note per section. If you exceed
this number consistently, consider rewriting the notes as main body text.
Use cautions, warnings, and dangers to alert readers of potential
problems or pitfalls. Use conditional phrases in cautions and warnings,
such as "If you do X, then Y will occur."
Use cautions and warnings to alert readers of potential problems or pitfalls.
Use conditional phrases in cautions and warnings, such as "If you do X, then Y
will occur."
These are examples of typical notices and the conditions for their usage:
.. note::
Notes are extra bits of information, supplementary to the main
flow. Notes should be relatively short. If the note content is
a short paragraph, consider rewriting the note as body text.
Notes are extra bits of information that supplement the main content. Notes
should be relatively short.
.. caution::
Cautions are low-level hazard messages that alert the user of
possible equipment, product, and software damage, including loss
of data.
Cautions are low-level hazard messages that alert the user of possible
equipment, product, and software damage, including loss of data.
.. warning::
Warnings are mid-level hazards that are likely to cause product
damage as well as bodily injury to humans. The most common warning
is for electrical hazards.
.. danger::
Dangers are high-level hazards that are likely to cause product
damage as well as bodily injury and even death to humans.
Warnings are mid-level hazards that are likely to cause product damage.
Links
*****
Use the standard `reST markup for links`_.
To add a link to another documentation page, use the `:ref:` role:
To add a cross-reference 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.
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 like this:
For example, an external link is defined at the bottom of the page like this:
.. code-block:: rest
.. _wiki about dogs: https://en.wikipedia.org/wiki/Dog
The same link is used in the content like this:
The defined link is then used in the content like this:
.. code-block:: rest
Check out the great `wiki about dogs`_.
Images
******
@@ -440,8 +429,8 @@ Follow these guidelines when using graphics in support of your documentation:
* Place the image immediately after the text it helps clarify, or as close as
possible.
* Use the `Sphinx figure directive`_ to insert images and figures into the document.
Include both alt text and a figure name and caption.
* Use the `Sphinx figure directive`_ to insert images and figures into the
document. Include both alt text, a figure name, and caption.
For example:
@@ -3,28 +3,23 @@
Writing guide
#############
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:
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 organizing content and how
we use reStructuredText and Sphinx.
.. contents:: :local:
:depth: 1
Use simple English
******************
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.
unecessary complicated or technical terms. Make the content accessible to
non-native speakers.
Be brief
========
@@ -37,24 +32,24 @@ Introduction, body, and conclusion.
Be friendly
===========
We write for our peers and want to be familiar. Use the second person,
you or we. Be professional, respectful, and cooperative.
We write for our peers and want to be familiar. Use the second person, you or
we. Be professional, respectful, and cooperative.
Assume your audience has the same level of technical understanding and
expertise as you did when you first started collaborating. Do not talk
down to our readers, but also do not assume they know everything about
the subject. Offer brief explanations or summaries of common knowledge
if a significant portion of readers might benefit.
Assume your audience has the same level of technical understanding and expertise
as you did when you first started collaborating. Do not talk down to our
readers, but also do not assume they know everything about the subject. Offer
brief explanations or summaries of common knowledge if a significant portion of
readers might benefit.
Use simple words
================
Use simple words to increase reader comprehension and reduce ambiguity.
Follow our tips for making good word choices:
Use simple words to increase reader comprehension and reduce ambiguity. Follow
our tips for making good word choices:
* **Avoid jargon**: Write for your audience, using everyday language
where possible, and technical terms where appropriate. Avoid clichés,
idioms, and metaphors.
* **Avoid jargon**: Write for your audience, using everyday language where
possible, and technical terms where appropriate. Avoid clichés, idioms, and
metaphors.
* **Be consistent**: Use one term for each concept or action and use it
consistently.
* **Avoid "fancy" words and phrases**: If there is a simpler word or phrase,
@@ -82,42 +77,39 @@ 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.
Avoid using the product name in page titles and headings.
Make content scannable
**********************
Organize your content to make it scannable for the reader, which
helps them find what they need quickly, and helps them understand more
efficiently.
Organize your content to make it scannable for the reader, which helps them find
what they need quickly, and helps them understand more efficiently.
* **Put the most important content first.** Make sure your introduction
clearly communicates what the reader can find on the page. Organize
supporting information towards the end of the page.
* **Put the most important content first.** Make sure your introduction clearly
communicates what the reader can find on the page. Organize supporting
information towards the end of the page.
* **Write scannable headings.** Think of headings as the outline for your
content. Write headings that are short, specific, and use `Parallelism`_.
Top level headings should show the most important subjects on the page.
* **Write great link text.** Great link text tells the reader what they
can expect when they click on a link. It also helps make the page more
scannable. Follow our guidelines for writing `Link text`_.
* **Write great link text.** Great link text tells the reader what they can
expect when they click on a link. It also helps make the page more scannable.
Follow our guidelines for writing `Link text`_.
Link text
=========
All links in content should follow these guidelines:
* **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.
* **Use unique link text**: Each link on a page should be unique. If users
see the same link text twice on a page, they'll assume it goes to the
same place.
* **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.
* **Use unique link text**: Each link on a page should be unique. If users 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 to help users scan the text.
* **Avoid generic text**: Don't use generic, uninformative link text such
as "click here" or "read more".
* **Avoid generic text**: Don't use generic, uninformative link text such as
"click here" or "read more".
For example:
@@ -129,14 +121,14 @@ For example:
Use strong verbs
****************
Passive verbs make writing stuffy and formal. Use strong verbs to get to
the point and avoid unnecessary words and phrases.
Passive verbs make writing stuffy and formal. Use strong verbs to get to the
point and avoid unnecessary words and phrases.
Use imperatives
===============
Commands, also called imperatives, are the fastest and most direct way of
giving someone instructions.
Commands, also called imperatives, are the fastest and most direct way of giving
someone instructions.
For example:
@@ -320,17 +312,6 @@ For example:
* Widget Pro version 5.0
* Widget Master v2.1.12
Terms using a hyphen or slash
-----------------------------
Capitalize only the first letter of terms using a hyphen or slash, even if they
are headings.
For example:
* Day/night Menu
* Follow-up Action Items
Contractions
============
@@ -365,32 +346,5 @@ For example:
**Not this:** Mom, Dad and I are going to the game.
Commas in numbers
-----------------
Use commas to divide large numbers into sets of three digits. Use periods for
decimal points.
Colons ":"
----------
If the text following a colon is a sentence, capitalize the first word after the
colon. If the text after a colon is not a sentence, do not capitalize the first
term unless it is a title.
For example:
* This is a capitalization example: Donuts do not cause holes.
* 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.
Do not use a colon to introduce graphics, tables, or sections.
Do not use a colon at the end of a task title or heading.
.. _click here: https://en.wikipedia.org/wiki/Dog
.. _dog wiki article: https://en.wikipedia.org/wiki/Dog