Measure The Load Performance, Accessibility, And SEO Of Your Documentation Pages

Technical Writing

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 your documentation site is an asset or a liability.

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

The Audits panel of DevTools is an automated diagnostics tool that helps web developers measure and find ways to improve the quality of a page. You can use the Audits panel to get an idea of the quality of your documentation site. You don't need to know anything about web development to use the Audits panel. Some suggestions are addressable within your content files. Others can only be addressed by web developers. At the very least, if you know that your documentation site is crappy, but can't convince managers to prioritize fixing it, you can now show them concrete proof of problems.

Load performance?

The importance of accessibility and SEO probably needs no explaining. Load performance might be less obvious. Load performance refers to how fast your documentation pages load. I define the mission of technical writers as helping users get tasks done as quickly and efficiently as possible. The faster a documentation page loads, the faster a user can get a task done.

Maybe you're thinking that no one really cares or notices if a page loads in 5 seconds or 10. There's actually lots of evidence that web users have low tolerance for slow-loading pages. If your readers are in a rush or panicked, I suspect that they may have even lower tolerance than usual.

Get started

  1. Open Google Chrome.

  2. Visit the URL that you want to audit. I'm going to audit the DevTools homepage as an example.

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

    The viewport on the left, and DevTools on the right.
    Figure 2. The viewport on the left, and DevTools on the right.
  4. Open the Audits panel.

    The Audits panel.
    Figure 3. The Audits panel.
  5. 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. See Appendix: Configuration options if most of your readers visit your site on desktops.

    It's very important to keep the options the same across audits. Every page loads slower when you simulate mobile. So if you simulate mobile on your first audit, and then use a desktop configuration on your second audit, the page will seem to load much faster when in reality it's only because of the inconsistent configuration options.

  6. Click Run Audits. After 10 or 20 seconds the Audits panel provides a report describing ways to improve the page.

    The viewport on the left, and a report for that page on the right.
    Figure 4. The viewport on the left, and a report for that page on the right.

    In Figure 4 you can see that the DevTools documentation itself doesn't have very good scores. I'm not happy about this, but it's largely out of my control. To show that I'm not a complete "do as I say, not as I do" hypocrite I'll mention that the scores here on kayce.basqu.es, which I built myself, are much more solid.

    A report on my homepage.
    Figure 5. A report on my homepage.
  7. 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.

    Hovering over the First Contenful Paint metric.
    Figure 6. Hovering over the First Contenful Paint metric.
  8. Expand an audit to learn more about it.

    Learning more about the Preload Key Requests audit.
    Figure 7. Learning more about the Preload Key Requests audit.
  9. Click Learn More for more information on why the audit is important and how to fix the page so that it passes the audit.

    Documentation for the Preload Key Requests audit.
    Figure 8. Documentation for the Preload Key Requests audit.

Caveats

Accessibility

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

SEO

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

Next steps

Here's the general workflow for using this information to improve page quality:

  1. Audit one of your documentation pages.
  2. Read your report and explore the suggestions. Look for changes that you can make within your content files. Examples include missing alt attributes on images, oversized images, and unoptimized images.
  3. Make the changes, and then run another audit to make sure your changes fixed the problem.

Send me questions and comments at kayce@basqu.es.

Appendix: Configuration options

In Get started I told you to keep the configuration options at their default values. If most of your documentation readers visit your site on desktops, you might want to set the Device option to Desktop and the Throttling option to No Throttling to more closely reflect the desktop experience.