lighthouse

[kaycebasques]

<h1 id="title">Measure The Load Performance, Accessibility, And SEO Of Your Documentation Pages</h1>

<p id="time">
  <time datetime="2019-04-25">2019 April 25</time>
</p>

<p id="category">Technical Writing</p>

<p id="summary">
  The experience of using a documentation site may be as important as the quality of the content
  on that site. This post shows you how to use Chrome DevTools to quantitatively measure
  whether a site is an asset or a liability.
</p>

Back when I joined Google 4 years ago I didn't know much about web development. By and large I
suspect that this is the case for most technical writers. Which is kind of curious if you stop
and think about it. 

My team at Google has a very broad mandate.

I joined Google 4 years ago. I didn't know much about web development at the time, but I was
assigned to a team that writes documentation for web developers. We have a very broad mandate.
Our goal is to look out for the health of the web at large. We want people to enjoy using the web,
because that's generally good for Google.

My particular contribution 

I write the documentation for Chrome DevTools. DevTools is Google Chrome's built-in set of
tools for web developers. When you're developing a website and it's not working correctly, you use
DevTools to figure out what's going wrong.

My team has a very broad mandate. Our goal is to improve the experience of browsing the web at large.
For example, 

By and large I suspect 

By and large I wager that most technical writers don't know much about web development. If you
stop and think about it, this is pretty curious.

So, in order to document DevTools well, I've had to learn a lot about web development. As I've learned
more about web development, and the web ecosystem at large

Back when I joined Google 4 years ago I didn't know much about web development. I was assigned this role
but ended up enjoying it a lot.

The Audits panel of DevTools is an automated diagnostics tool that helps web developers measure
and improve the quality of a page. The engine that powers the Audits panel is called Lighthouse,
so those 2 phrases will be used interchangeably throughout this post.

You can use the Audits panel to discover problems with your documentation pages. You don't need to know
much about web development to use the tool. First I'll show you how to use the tool and then I'll discuss
how to act on the information that it provides.

<h2 id="terms">Lighthouse and the Audits panel</h2>

This post uses these 2 names interchangeably. Lighthouse is the auditing engine that powers the Audits
panel.

<h2 id="audience">Audience</h2>

<h2 id="getstarted">Get started</h2>

[chrome]: https://www.google.com/chrome/

1. Open [Google Chrome][chrome].
1. Visit the URL that you want to audit.

     <figure>
       <img src="/media/lighthouse1.png"
            alt="The DevTools homepage."/>
       <figcaption>
         <b>Figure 1</b>. The DevTools homepage.
       </figcaption>
     </figure>

[viewport]: https://developer.mozilla.org/en-US/docs/Glossary/Viewport

1. Right-click anywhere on the page and select **Inspect**. If you've never used DevTools before,
   it opens to the right of your [viewport][viewport] by default.

     <figure>
       <img src="/media/lighthouse2.png"
            alt="The viewport on the left, and DevTools on the right."/>
       <figcaption>
         <b>Figure 2</b>. The viewport on the left, and DevTools on the right.
       </figcaption>
     </figure>

1. Open the **Audits** panel.

     <figure>
       <img src="/media/lighthouse3.png"
            alt="The Audits panel."/>
       <figcaption>
         <b>Figure 3</b>. The Audits panel.
       </figcaption>
     </figure>

1. Keep the configuration options at their default values. Technically, these options set up
   the Audits panel to simulate the experience of viewing this page on a mobile device but for your
   purposes these options are mostly irrelevant.
1. Click **Run Audits**. After 10 or 20 seconds the Audits panel provides a report describing ways to
   improve the page.

     <figure>
       <img src="/media/lighthouse4.png"
            alt="The viewport on the left, and a report for that page on the right."/>
       <figcaption>
         <b>Figure 4</b>. The viewport on the left, and a report for that page on the right.
       </figcaption>
     </figure>

     In **Figure 4** you can see that the DevTools documentation itself doesn't have very
     good scores. Which is frankly a blight on our reputation.

     In **Figure 4** you'll notice that the DevTools documentation itself doesn't have very good scores.
     This keeps me up at night.

1. Hover over a metric to learn more about what it's measuring. There are many metrics related to
   load performance because web developers conceptualize the loading experience as a series of key
   events, such as when content is first painted to the screen and when the page appears fully loaded.

     <figure>
       <img src="/media/lighthouse5.png"
            alt="Hovering over the First Contenful Paint metric."/>
       <figcaption>
         <b>Figure 5</b>. Hovering over the First Contenful Paint metric.
       </figcaption>
     </figure>

1. Expand an audit to learn more about it.

     <figure>
       <img src="/media/lighthouse6.png"
            alt="Learning more about the Preload Key Requests audit."/>
       <figcaption>
         <b>Figure 6</b>. Learning more about the Preload Key Requests audit.
       </figcaption>
     </figure>

1. Click **Learn More** for more information on why the audit is important and how to fix the page so
   that it passes the audit.

     <figure>
       <img src="/media/lighthouse7.png"
            alt="Documentation for the Preload Key Requests audit."/>
       <figcaption>
         <b>Figure 7</b>. Documentation for the Preload Key Requests audit.
       </figcaption>
     </figure>

     P.S. I wrote most of this documentation.

<h2 id="perf">Load performance</h2>

[perf]: https://medium.com/@vikigreen/impact-of-slow-page-load-time-on-website-performance-40d5c9ce568a

The importance of accessibility and SEO probably need no explaining. Load performance might be less obvious.
There's lots of [evidence][perf] that web users have low tolerance for slow-loading pages. 

As technical writers, our job is to help users get tasks done. If our users are in a
rush, or are panicked, they're probably even more sensitive to our slow-loading documentation pages than usual.
In other words, you might be able to improve user satisfaction with your documentation just by making your site faster.

<h2 id="caveats">Caveats</h2>

<h3 id="a11y">Accessibility</h3>

The accessibility audits are not comprehensive. A site can get a perfect score of 100 on accessibility
and still be miserably inaccessible. Here's why. A page is accessible when:

1. A user can navigate it with a keyboard or screen reader.
1. The page's elements are properly annotated for screen readers. In other words, as a screen reader
   user navigates the page, the screen reader properly announces and interacts with the element in
   focus.

The Audits panel measures #2. #1 is omitted only because it's hard to automate, not because it's an optional
consideration. #1 is just as important as #2. The best way to test for #1 is to manually navigate your
documentation site with a keyboard or screen reader.

<h3 id="seo">SEO</h3>

Likewise, the SEO audits are not comprehensive. They're pretty basic, in fact. But it's a start.

<h2 id="implementation">Implementation</h2>

Most of the suggestions can only be implemented by web developers. But you can use the report that the
Audits panel generates as concrete proof of problems.

Some of the suggestions can be implemented within your content. For example, suppose that for some reason you
mark up images as HTML within your Markdown:

    # Overview

    The Confabulator can help you confabulate your
    widgetometers with 50% less misery.

    <img src="/images/confabulator.png"/>

After running a report the Audits panel tells you that your images are not labelled properly for screen readers.
Fixing this audit is just a matter of adding `alt` attributes to your images:

    # Overview

    The Confabulator can help you confabulate your
    widgetometers with 50% less misery.

    <img src="/images/confabulator.png"
         alt="Tweaking a widgetometer with the Confabulator to
              achieve 34% less existential dread."/>

<h2 id="validation">Validation</h2>

After implementing a change, generate another report to make sure that you're now passing the audit that you
were previously failing. Make sure to keep the configuration options consistent between reports.

<h2 id="feedback">Feedback</h2>

Hopefully by now you get the general idea. Email me at kayce@google.com if you want to lament
about how terrible your site is, or gloat about how amazing it is, or if you have any questions or comments.