Documentation Page

Best Practices

People often arrive at a documentation page after visiting the landing page or after searching for a specific piece of information. Documentation pages don’t need to provide as much contextualizing information as more introductory pages. The copy should be clear, focused, and concise.

• Use Plain Language, not technical jargon.
• Provide useful information.
• See Voice and Tone for more information.

Usage

Go to Internal Preview

<!-- Place an appropriate title for the page here -->
<div class="container-fluid">
  <div class="row">
    <div class="col-12 col-lg-6">
      <section class="card">
        <div class="card-body">
          <details class="page-contents" id="toc">
            <summary class="summary">
              <h2 class="h6 d-inline" id="on-this-page">On this page:</h2>
            </summary>
            <nav aria-labelledby=“on-this-page”>
              <div class="toc">
                <ol>
                  <li><a href="#">Heading X</a>
                  </li>
                  <li><a href="#">Heading X</a>
                  </li>
                </ol>
              </div>
            </nav>
          </details>
        </div>
      </section>
    </div>
  </div>
</div>
<div class="content-container">
  <div class="container-fluid">
    <div class="row">
      <div class="col-12">
        <h2>Level 2 Heading (H2)</h2>
        <p>The page heading communicates the main focus of the page. Make your page heading descriptive and keep it succinct.</p>
        <h3>Level 3 Heading (H3)</h3>
        <p>These headings introduce, respectively, sections and subsections within your body copy. As you create these headings, follow the same guidelines that you use when writing section headings: Be succinct, descriptive, and precise.</p>
        <p>Use the side navigation menu to help your users quickly skip to different H3 and H4 sections of your page. The menu is best suited to displaying a hierarchy with one to two levels and, as we mentioned, to display the sub-navigation of a given page. Keep each section and subsection focused — a good approach is to include one theme (topic) per section.</p>
      </div>
    </div>
  </div>
</div>
<!-- Follow this section with necessary navigation prompts -->

Go to Public Preview

<!-- Place an appropriate title for the page here -->
<div class="container-fluid">
  <div class="row">
    <div class="col-12 col-lg-3">
      <section class="card">
        <div class="card-body">
          <details class="page-contents" id="toc">
            <summary class="summary">
              <h2 class="h6 d-inline" id="on-this-page">On this page:</h2>
            </summary>
            <nav aria-labelledby=“on-this-page”>
              <div class="toc">
                <ol>
                  <li><a href="#">Heading X</a>
                  </li>
                  <li><a href="#">Heading X</a>
                  </li>
                </ol>
              </div>
            </nav>
          </details>
        </div>
      </section>
    </div>
    <div class="col-12 col-lg-9">
      <div class="card h-100">
        <div class="card-body">
          <h2>Level 2 Heading (H2)</h2>
          <p>The page heading communicates the main focus of the page. Make your page heading descriptive and keep
          it succinct.</p>
          <h3>Level 3 Heading (H3)</h3>
          <p>These headings introduce, respectively, sections and subsections within your body copy. As you create
          these headings, follow the same guidelines that you use when writing section headings: Be succinct,
          descriptive, and precise.</p>
          <p>Use the side navigation menu to help your users quickly skip to different H3 and H4 sections of your
          page. The menu is best suited to displaying a hierarchy with one to two levels and, as we mentioned,
          to display the sub-navigation of a given page. Keep each section and subsection focused — a good
          approach is to include one theme (topic) per section.</p>
        </div>
      </div>
    </div>
  </div>
</div>
<!-- Follow this section with necessary navigation prompts -->

Resources

• Plain Language.gov