Templates

Documentation page

Present information on a certain theme, topic, or idea.

About the documentation page template

People often arrive at a documentation page after visiting the landing page or after searching for a specific piece of information, so documentation pages don’t need to provide as much contextualizing information as more introductory pages would. The copy should be clear, focused, and concise.
Documentation page Demo Documentation page 
<a class="usa-skipnav" href="#main-content">Skip to main content</a>
  <section class="usa-banner" aria-label="Official government website">
  <div class="usa-accordion">
    <header class="usa-banner__header">
      <div class="usa-banner__inner">
        <div class="grid-col-auto">
          <img
            class="usa-banner__header-flag"
            src="/preview/uswds/uswds-site/dw-add-getting-started-for-devs/assets/img/us_flag_small.png"
            alt="U.S. flag"
          />
        </div>
        <div class="grid-col-fill tablet:grid-col-auto">
          <p class="usa-banner__header-text">
            An official website of the United States government
          </p>
          <p class="usa-banner__header-action" aria-hidden="true">
            Here’s how you know
          </p>
        </div>
        <button
          class="usa-accordion__button usa-banner__button"
          aria-expanded="false"
          aria-controls="gov-banner"
        >
          <span class="usa-banner__button-text">Here’s how you know</span>
        </button>
      </div>
    </header>
    <div class="usa-banner__content usa-accordion__content" id="gov-banner">
      <div class="grid-row grid-gap-lg">
        <div class="usa-banner__guidance tablet:grid-col-6">
          <img
            class="usa-banner__icon usa-media-block__img"
            src="/preview/uswds/uswds-site/dw-add-getting-started-for-devs/assets/img/icon-dot-gov.svg"
            role="img"
            alt=""
            aria-hidden="true"
          />
          <div class="usa-media-block__body">
            <p>
              <strong> Official websites use .gov </strong>
              <br />
              A <strong>.gov</strong> website belongs to an official government
              organization in the United States.
            </p>
          </div>
        </div>
        <div class="usa-banner__guidance tablet:grid-col-6">
          <img
            class="usa-banner__icon usa-media-block__img"
            src="/preview/uswds/uswds-site/dw-add-getting-started-for-devs/assets/img/icon-https.svg"
            role="img"
            alt=""
            aria-hidden="true"
          />
          <div class="usa-media-block__body">
            <p>
              <strong> Secure .gov websites use HTTPS </strong>
              <br />
              A <strong>lock</strong> (
              <span class="icon-lock"
                ><svg
                  xmlns="http://www.w3.org/2000/svg"
                  width="52"
                  height="64"
                  viewBox="0 0 52 64"
                  class="usa-banner__lock-image"
                  role="img"
                  aria-labelledby="banner-lock-title banner-lock-description"
                  focusable="false"
                >
                  <title id="banner-lock-title">Lock</title>
                  <desc id="banner-lock-description">A locked padlock</desc>
                  <path
                    fill="#000000"
                    fill-rule="evenodd"
                    d="M26 0c10.493 0 19 8.507 19 19v9h3a4 4 0 0 1 4 4v28a4 4 0 0 1-4 4H4a4 4 0 0 1-4-4V32a4 4 0 0 1 4-4h3v-9C7 8.507 15.507 0 26 0zm0 8c-5.979 0-10.843 4.77-10.996 10.712L15 19v9h22v-9c0-6.075-4.925-11-11-11z"
                  /></svg
              ></span>
              ) or <strong>https://</strong> means you’ve safely connected to
              the .gov website. Share sensitive information only on official,
              secure websites.
            </p>
          </div>
        </div>
      </div>
    </div>
  </div>
</section>

  <div class="usa-overlay"></div>
<header class="usa-header usa-header--basic">
  <div class="usa-nav-container">
    <div class="usa-navbar">
      <div class="usa-logo" id="basic-logo">
        <em class="usa-logo__text">
          <a href="javascript:void(0)" title="&lt;Project title&gt;">
            &lt;Project title&gt;
          </a>
        </em>
      </div>
      <button class="usa-menu-btn">Menu</button>
    </div>
    <nav aria-label="Primary navigation" class="usa-nav">
      <button class="usa-nav__close">
        <img src="/preview/uswds/uswds-site/dw-add-getting-started-for-devs/assets/img/usa-icons/close.svg" role="img" alt="Close" />
      </button>
      <ul class="usa-nav__primary usa-accordion">
        <li class="usa-nav__primary-item">
          <button
            class="usa-accordion__button usa-nav__link usa-current"
            aria-expanded="false"
            aria-controls="basic-nav-section-one"
          >
            <span>&lt;Current section&gt;</span>
          </button>

          <ul id="basic-nav-section-one" class="usa-nav__submenu">
            <li class="usa-nav__submenu-item">
              <a href="#"> &lt;Navigation link&gt; </a>
            </li>
            <li class="usa-nav__submenu-item">
              <a href="#"> &lt;Navigation link&gt; </a>
            </li>
            <li class="usa-nav__submenu-item">
              <a href="#"> &lt;Navigation link&gt; </a>
            </li>
          </ul>
        </li>
        <li class="usa-nav__primary-item">
          <button
            class="usa-accordion__button usa-nav__link"
            aria-expanded="false"
            aria-controls="basic-nav-section-two"
          >
            <span>&lt;Section&gt;</span>
          </button>

          <ul id="basic-nav-section-two" class="usa-nav__submenu">
            <li class="usa-nav__submenu-item">
              <a href="#"> &lt;Navigation link&gt; </a>
            </li>
            <li class="usa-nav__submenu-item">
              <a href="#"> &lt;Navigation link&gt; </a>
            </li>
            <li class="usa-nav__submenu-item">
              <a href="#"> &lt;Navigation link&gt; </a>
            </li>
          </ul>
        </li>
        <li class="usa-nav__primary-item">
          <a href="javascript:void(0)" class="usa-nav__link">
            <span>&lt;Simple link&gt;</span>
          </a>
        </li>
      </ul>

      <form class="usa-search usa-search--small" role="search">
        <label class="usa-sr-only" for="basic-search-field-en-small">
          Search
        </label>
        <input
          class="usa-input"
          id="basic-search-field-en-small"
          type="search"
          name="search"
        />
        <button class="usa-button" type="submit">
          <span class="usa-sr-only">Search</span>
        </button>
      </form>
    </nav>
  </div>
</header>

  <div class="usa-section">
  <div class="grid-container">
    <div class="grid-row grid-gap">
      <div class="usa-layout-docs__sidenav desktop:grid-col-3">
        <nav aria-label="Secondary navigation">
          <ul class="usa-sidenav">
            <li class="usa-sidenav__item">
              <a href="javascript:void(0);">Parent link</a>
            </li>
            <li class="usa-sidenav__item">
              <a href="javascript:void(0);" class="usa-current">Current page</a>
              <ul class="usa-sidenav__sublist">
                <li class="usa-sidenav__item">
                  <a href="javascript:void(0);">Child link</a>
                </li>
                <li class="usa-sidenav__item">
                  <a href="javascript:void(0);" class="usa-current"
                    >Child link</a
                  >
                  <ul class="usa-sidenav__sublist">
                    <li class="usa-sidenav__item">
                      <a href="javascript:void(0);">Grandchild link</a>
                    </li>
                    <li class="usa-sidenav__item">
                      <a href="javascript:void(0);">Grandchild link</a>
                    </li>
                    <li class="usa-sidenav__item">
                      <a href="javascript:void(0);" class="usa-current"
                        >Grandchild link</a
                      >
                    </li>
                    <li class="usa-sidenav__item">
                      <a href="javascript:void(0);">Grandchild link</a>
                    </li>
                  </ul>
                </li>
                <li class="usa-sidenav__item">
                  <a href="javascript:void(0);">Child link</a>
                </li>
                <li class="usa-sidenav__item">
                  <a href="javascript:void(0);">Child link</a>
                </li>
                <li class="usa-sidenav__item">
                  <a href="javascript:void(0);">Child link</a>
                </li>
              </ul>
            </li>
            <li class="usa-sidenav__item">
              <a href="javascript:void(0);">Parent link</a>
            </li>
          </ul>
        </nav>
      </div>

      <main
        class="usa-layout-docs__main desktop:grid-col-9 usa-prose usa-layout-docs"
        id="main-content"
      >
        <h1>Page heading (h1)</h1>

        <p class="usa-intro">
          The page heading communicates the main focus of the page. Make your
          page heading descriptive and keep it succinct.
        </p>

        <h2 id="section-heading-h2">Section heading (h2)</h2>

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

        <h3 id="section-heading-h3">Subsection heading (h3)</h3>

        <p>
          The particulars of your body copy will be determined by the topic of
          your page. Regardless of topic, it’s a good practice to follow the
          inverted pyramid structure when writing copy: Begin with the
          information that’s most important to your users and then present
          information of less importance.
        </p>

        <p>
          Keep each section and subsection focused — a good approach is to
          include one theme (topic) per section.
        </p>

        <h4 id="section-heading-h4">Subsection heading (h4)</h4>

        <p>
          Use the side navigation menu to help your users quickly skip to
          different sections of your page. The menu is best suited to displaying
          a hierarchy with one to three levels and, as we mentioned, to display
          the sub-navigation of a given page.
        </p>

        <p>
          Read the full documentation on our side navigation on the component
          page.
        </p>
      </main>
    </div>
  </div>
</div>

Guidance

When to use the documentation page template

  • Detailed information on a specific topic. If you’re presenting detailed information on a specific topic or theme that has already been contextualized by a landing page. Some topics that can be nicely represented on this type of page include guides or how-tos, technical documentation, and program descriptions — in short, any subject that requires in-depth explanation.

When to consider something else

  • Introducing a new program. Don’t use a documentation page to introduce your users to your agency or organization — the landing page is better suited to that purpose. The level of detail present on documentation pages can overwhelm users who are just becoming acquainted with your organization.

Usability guidance

  • Use a precise headline. A precise headline quickly communicates your page’s purpose. If the page content is especially complex, you may consider using a subheadline to further clarify its meaning.
  • Write concise copy. Favor short sentences (and paragraphs) over longer ones, and use straightforward language, avoiding jargon. Remember, copy blocks don’t need to be long to be comprehensive.
  • See component-specific guidance. For guidance on specific components, see the page for the individual components.

Components used in this template