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. This document describes our organization and formatting guidelines.

Refer to Writing guide to learn how we keep our documents clear and concise.

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:

You can view the content directly in the .rst markup files, or generate the HTML content by installing and building 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.

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 guidelines page toctree looks like:

.. toctree::
   :maxdepth: 1

   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.

For example, this page “Structure and formating” has the label .. _structure-formatting:

.. _structure-formatting:

Structure and formatting
########################

This page can then be referenced from other pages in the documentation using the :ref: role:

:ref:`structure-formatting`

Documentation organization

The documentation is organized into five general sections:

  1. Concepts: Introduction and overview of Clear Linux OS specific concepts or features.
  2. Get started: Information about getting started with Clear Linux OS.
  3. Guides: Detailed information and instruction on using Clear Linux OS features.
  4. Tutorials: Step-by-step instruction for using Clear Linux OS in specific use cases.
  5. Reference: Supplementary and reference information for Clear Linux OS.

Page structure

Each page in the documentation should follow the basic format of:

  • 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)

Headings

Use headings to section and organize your content for better readability and clarity.

  • All files must have a top level heading, which is the title for the page.
  • Up to three additional levels of headings are allowed under the title heading.
  • Each heading should be followed by at least one paragraph of content. Avoid two or more consecutive headings.

Refer to the Writing guide for tips on using headings to create scannable content.

To mark up headings in the .rst file:

  • Use hash-tags to underline the file’s main title:

    Main title
##########

  • Use asterisks to underline the file’s first level headings:

    First level heading
*******************

  • Use equal signs to underline the file’s second level of headings:

    Second level heading
====================

  • Use dashes to underline the file’s third level of headings:

    Third level heading
-------------------

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.

Use the standard reST contents directive with depth: 1 for quick links.

Inline text formatting

We use the Microsoft Writing Style Guide as our starting point for text 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 Define acronym when first used. After first use and definition, use the acronym only.

Use the :abbr: role, in the following format:

:abbr:`Acronym (Def)`
Bundle names Bold Use the :command: role.
Callouts   Use .. note::
Code/command examples Monospace, visually distinct from rest of text. Use an indented call-out box. Use .. code-block:: with the correct language setting.
Commands Bold Use the :command: role.
Command flags Bold Use the :command: role.
Console output Monospace, visual distinction from rest of text. Use an indented call-out box. Use .. code-block:: with console as the language setting.
Emphasis Italic *strong*
Environment variables Use the case format of the environment variable. Use :envvar:
Example commands with optional or replaceable parts

Use angle brackets for swapping in the specific name, 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 subsequent uses.

If it is used outside of the source of definition, link the term.

 *term*
Product name Follow correct trademark and attribution guidelines.  
Tool names

Correctly capitalized, no quotes, bold, or italics as the basic rule.

If the tool name is the command, like most Linux tools, treat it like a command.

If the tool name is lowercase and used at the start of a sentence, use bold.

  

White space and line length

Limit line length to 78 characters. The GitHub web interface forces this limitation for readability.

Remove trailing whitespace from your documents.

Code blocks and examples

When providing example code or commands use the Sphinx code-block directive. Select the appropriate syntax highlighting for the example command or code.

For example, if showing console output, use console highlighting:

.. code-block:: console

Sphinx provides other ways of marking up example code if needed.

Lists and instructions

Use a numbered list when the order or priority of the items is important, such 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 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:

  • 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, 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 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 looping.
  • Avoid over-using numbered lists, except in procedural documents such as tutorials and step-by-step guides.

Bulleted lists

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 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.

Use the correct ending punctuation for sentence style bullet lists. For example:

Use this:

When setting the user code, remember:

* Use a number that has a meaning for you.
* 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:

  • Each step (list item) should describe one action.

  • If the same steps are repeated, refer to the earlier steps rather than repeating them.

  • When a step includes a command or code block as an example, put the command or code block after the step that includes them.

  • Use supporting images where appropriate. If the series of steps is supported by one figure, refer to the figure in the introductory text.

    For example: “See Figure 15 and do the following:”

    When a series of steps is supported by two or more figures, refer to the specific figure in the relevant step and show the figure immediately after the reference. Do not write: “See figures 15 through 22 and do the following:”

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 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.

Use the standard reST admonition directive.

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 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:

注解

Notes are extra bits of information that supplement the main content. Notes should be relatively short.

警告

Cautions are low-level hazard messages that alert the user of possible equipment, product, and software damage, including loss of data.

警告

Warnings are mid-level hazards that are likely to cause product damage.

Images

Use images or figures to convey information that may be difficult to explain using words alone. Well-planned graphics reduce the amount of text required to explain a topic or example.

Follow these guidelines when using graphics in support of your documentation:

  • 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.

  • Use either PNG or JPEG bitmap files for screenshots and SVG files for vector graphics.

  • 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, a figure name, and caption.

    For example:

    .. figure:: figures/topic-1.png
   :alt: An image supporting the topic.

   Figure 1: This is the figure 1 caption.

  • Include at least one direct reference to an image from the main text, using the figure number. For example:

    Use this:

    Figure 1

    Not this:

    The figure above or below

Images should follow these naming and location conventions:

  • Save the image files in a figures folder at the same level as the file that will reference the image.
  • Name image files according to the following rules:
    • Use only lower case letters.
    • Separate multiple words in filenames using dashes.
    • Name images using the filename of the file they appear on and add a number to indicate their place in the file. For example, the third figure added to the welcome.rst file must be named welcome-3.png.