Editing 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

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

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

Key points

The Key Point banner at the top of the page is a way to briefly show the most important point in the page, so that a visitor to the page can quickly and easily check on the most common and most important style points. In some cases, you may include more than one key point in the Key Point banner, but even if the page has more than one key point, put all of the key points at the top of the page so readers can find them easily.

If a given page has no particular most important points, then leave out the Key Point banner.

Some style guide pages have a Key Point banner that summarizes the topic rather than presenting the most important point. We're working on removing such banners.

Formatting examples

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" tag—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 user 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.
  1. Click the search box and type custom function.
  2. Press Enter.

For more examples of tables, see the following:

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>