Edit the style guide

This page provides guidance for editors at Google about how to write and edit pages in the style guide.

If you want to propose a change to the style guide but you're not part of the group that owns the style guide, then we recommend making your suggestion by using the Send feedback button on an appropriate page of the style guide.

Follow the style guide

In general, the guidance in the style guide applies to style guide pages as well as to documentation, so follow the style guide's guidelines as you edit the style guide.

HTML and Markdown

Choose a format for a style guide page

If you're creating a new page, you can use HTML or Markdown, at your preference.

If you're editing an existing page, then don't change the file format. In particular, there are several style guide pages that are written in HTML specifically because they use formatting that's hard to replicate in Markdown. In theory, you can use HTML within a Markdown file, but in practice, there are many contexts where you can't.

Support Markdown in your guidance

When you provide guidance about what markup to use in a given situation, give guidance and examples for both HTML and Markdown.

(Some style guide pages don't yet follow this guidance.)

Code formatting

A few miscellaneous code-formatting notes:

• Don't go out of your way to manually reformat lines that you're not otherwise touching. There may be a reason that they're formatted the way they are.

• If the editing tool that you're using automatically formats lines, then don't manually reformat it in some other way.

• If possible, hard-wrap the lines that you're working on to 80 characters. But if doing so would be complicated or difficult, then don't.

• Put an extra blank line before each heading, to make it easier for a human to scan the source document.

Example formatting

When formatting examples in lists, you have two options:

• Add the list to a table with the following column headings:

  • Guidance (optional)
  • Recommended:
  • Not recommended:

• Indent the examples by using the class="example" attribute—for example:

  • <p class="example">
  • <div class="example">
  • <dd class="example">

List the Recommended examples before the Not recommended examples.

Example of using a table

Guidance	Recommended	Not recommended
You can introduce a procedure with an imperative statement. Don't introduce a procedure with a partial sentence that's completed by the numbered steps.	To customize the buttons, follow these steps: Customize the buttons:	To customize the buttons:
If the reader must press Enter after a step, then include that instruction as part of the step.	Click the search box, type custom function, and then press Enter.	Click the search box and type custom function. Press Enter.

For more examples of tables, see the following:

• More guidelines for writing procedures
• Sentence structure
• Plurals in parentheses
• Inclusive documentation

Examples of using indenting

The following sections contain examples of how you can use indenting to streamline lists of examples on a page.

Examples on a single line

For a single line of text, use <p class="example"> on each line.

Recommended: To customize the buttons, follow these steps:

Also recommended: Customize the buttons:

Not recommended: To customize the buttons:

In HTML, it looks like the following:

    <p class="example"><span class="compare-better">Recommended:</span> To
      customize the buttons, follow these steps:</p>
    <p class="example"><span class="compare-better">Also recommended:</span> Customize
      the buttons:</p>
    <p class="example"><span class="compare-worse">Not recommended:</span> To
      customize the buttons:</p>

Examples on multiple lines

For multiple lines of text, surround the entire block with <div class="example"> tags.

Recommended:

1. Click the search box, type custom function, and then press Enter.

Not recommended:

1. Click the search box and type custom function.
2. Press Enter.

In HTML, it looks like the following:

<div class="example">
    <p><span class="compare-better">Recommended:</span></p>
      <ol>
        <li>Click the search box, type <code>custom function</code>, and then
          press <b>Enter</b>.</li>
      </ol>
    <p><span class="compare-worse">Not recommended:</span></p>
      <ol>
        <li>Click the search box and type <code>custom function</code>.</li>
        <li>Press <b>Enter</b>.</li>
      </ol>
</div>

For more examples, see Procedures.

Examples in description lists

In description lists, such as the Word list, use the <dd class="example"> tag on each line.

check

Don't use to refer to marking a checkbox. Instead, use select.

Recommended: Select Automatically check for updates.

Not recommended: Check Automatically check for updates.

In HTML, it looks like the following:

<dt id="check" class="avoid"><span class="icon-avoid"></span>check</dt>
<dd>Don't use to refer to marking a checkbox. Instead, use <i>select</i>.</dd>
<dd class="example"><span class="compare-better">Recommended:</span> Select
  <b>Automatically check for updates</b>.</dd>
<dd class="example"><span class="compare-worse">Not recommended:</span> Check
  <b>Automatically check for updates</b>.</dd>

Note: If the examples come at the end of a bulleted list, but apply to all the bullets (not just the last one), either add another line of text between the bullets and the examples and then indent them, or don't indent them at all. Otherwise, the examples will look like they go with the last bullet. For an example of adding a sentence between the bullets and the example, see Footnotes. For an example of not indenting the example after a list, see Using k to indicate thousands.