Measure The Load Performance, Accessibility, And SEO Of Your Documentation Pages
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.
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.
Open Google Chrome.
Visit the URL that you want to audit. I'm going to audit the DevTools homepage as an example.
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.
Open the Audits panel.
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.
Click Run Audits. After 10 or 20 seconds the Audits panel provides a report describing ways to improve the page.
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.
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.
Expand an audit to learn more about it.
Click Learn More for more information on why the audit is important and how to fix the page so that it passes the audit.
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:
- A user can navigate it with a keyboard or screen reader.
- 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.
Likewise, the SEO audits are not comprehensive. They're pretty basic, in fact. But it's a start.
Here's the general workflow for using this information to improve page quality:
- Audit one of your documentation pages.
- Read your report and explore the suggestions. Look for changes that you can make within
your content files. Examples include missing
altattributes on images, oversized images, and unoptimized images.
- Make the changes, and then run another audit to make sure your changes fixed the problem.
Send me questions and comments at email@example.com.
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.