Content quality guidelines

Content quality guidelines

Read this page to learn the guiding principles of content quality on web.dev. The top-level sections of this page like Accuracy and Relevance represent core themes. The second-level sections like Know your audience represent more concrete guidelines for achieving each theme.

If you're already drafting or reviewing content and just need to quickly determine whether the content meets web.dev's quality guidelines, use the content checklist instead.

The long-term goal of this page is to provide concrete examples of each quality guideline, as well as research backing up each guideline. This page is primarily intended to teach web.dev authors why these quality guidelines are important, and how to concretely follow each guideline.

Accuracy

Follow best practices

Make sure your information aligns to current documentation, standards, and best practices.

Make sure you have relevant expertise

If you're writing about a topic that isn't in your area of expertise, get a subject matter expert to review your content.

Relevance

Know your audience

Canonical example: Identify slow third-party JavaScripts focuses on helping goal-driven problem solvers and helps them prioritize what to do based on how much time they have

Use the audience guidelines to keep a particular type of reader in mind as you write. These audience categories map to well-known user types across technical documentation. For example, someone who needs to just get a particular task done usually doesn't want to scan through a lot of conceptual information.

Explain why a user should care about your content

Canonical example: Use Imagemin to compress images leads off with a very straightforward explanation of how the guidance will make the reader's site better without sacrificing quality

Make sure your content is meeting a need of your audience. (For example, is it teaching them how to do something? Helping them grasp a commonly misunderstood concept?) Be upfront and explicit about explaining how your content will make the reader's life better.

Phrase your titles, subtitles, and descriptions with the needs and concerns of your readers in mind.

Don't

A post titled "The Media Capabilities API"

If the reader isn't familiar with the API, its name isn't meaningful and doesn't convey how the post will be useful.

Do

A post titled "How YouTube improved video performance with the Media Capabilities API"

While slightly longer, this title tells less experienced readers what they'll learn from the post while still providing the name of the API for readers who recognize it.

Help readers get things done

Canonical example: Precache with Workbox

Focus on readers and the concrete task they're trying to complete. While an introductory paragraph can provide important context, get to the instructional content as soon as possible.

When providing instruction, favor the imperative mood.

Don't

You can do x by clicking Run Audit.

The declarative mood ("you can…") makes it less clear that the reader needs to take an action.

Do

Click Run Audit to do x.

The imperative "click" makes it obvious that an action is needed.

When talking about technologies or tools, focus on what they let the reader do, not on their features or the work that went into creating them. (Avoiding first-person pronouns helps.)

Don't

We've added [a cool thing] in DevTools.

This sentence emphasizes the work the developers of DevTools did rather than what it lets the reader do.

Do

Use [a cool thing] in DevTools to [do neat stuff].

This sentence better focuses on what how readers can meet their goals.

Address the reader directly rather than imagining a hypothetical third party.

Don't

A seller can choose a variety of shopfront themes.

If the reader isn't a seller, this detail may not seem relevant.

Do

You can choose a variety of shopfront themes.

Using second person helps convey that we think this information is relevant to readers. (This strategy assumes that the post has been appropriately targeted to an audience.)

Provide a way to measure success. How can developers test that they've followed your instruction correctly?

Be mindful of the development landscape

Canonical example: Serve images in next-gen formats makes it clear that WebP is not supported in all browsers

Acknowledge browser complexity. Clearly state browser support (e.g., link to the relevant feature page on caniuse) and provide workarounds for browser incompatibilities (e.g., polyfills).

When selecting tooling, follow the advice in the Tooling and libraries post.

Omit irrelevant ideas

While tangents can sometimes be fun, web.dev readers usually come to the site with a specific task or goal in mind.

Readability

Be concise

Canonical example: Add a web app manifest

Use the fewest words possible while keeping language clear and readable.

Don't

Absolute and fixed positioning have been reimplemented and are more spec compliant than the old implementation. They also better match the behavior in other browsers.

This sentence includes unnecessary words in some places (e.g., multiple phrases saying there's a new version), while not providing enough detail in others (for example, which spec?).

Do

Absolute and fixed positioning are now more compliant with W3C specifications and better match the behavior in other browsers.

This revision gives detail readers will likely need (for example, the relevant specification) while omitting unnecessary words.

Keep posts and codelabs short—typically 1,000 words or less.

This emphasis on concision often means you can't discuss every aspect of a tool or technique. Instead, focus on the essential concepts required for readers to get started with a technique and apply it to their projects. If readers are interested in diving deeper, they can move on to resources outside of web.dev.

Accessibility

web.dev aims to be a world-class example of an accessible site. Common content problems include:

Instructional effectiveness and completeness

Use examples liberally

Examples are an extremely effective way to get ideas across.

This page itself is an example of the power of examples. See for yourself whether the guidelines with examples are easier to understand than the guidelines without examples. We're working on adding examples to every guideline.

Chunk your content

Dividing your content into logical chunks makes it easier to understand.

Use section headings and subheadings to convey the structure of your piece. There are two structures that tend to work well on web.dev (though feel free to try others!):

  • Measure → optimize → monitor

    This sequence works in many posts and is all but essential for posts about how to address Lighthouse audits.

  • Concept → how-to → further reading

    This sequence works well for codelabs.

Focus each paragraph (typically 2–3 sentences) on one main idea.

Use a list for a set of instructions or related ideas.

Include examples and figures. (See the next guideline.)

Keep it simple

Canonical example: Code splitting with React.lazy and Suspense

Focus on essential details when explaining a tool or technique. Avoid overwhelming the reader with "real-world" examples that include complexities that aren't required to understand the basic concept. Save those details for supplemental codelabs or follow-up posts.

Avoid jargon. If you absolutely must use a term most web.dev readers are unlikely to know, define it in a short aside. See the web.dev components post for how to include asides. Also check out the Inclusion and accessibility post for more info about writing readable language.

Don't

In some scripts, graphemes can be visually joined when they're adjacent.

Script and grapheme are very precise, but they're likely to be unfamiliar to most readers and may cause confusion since readers probably more commonly see script referring to a piece of code.

Do

In some written languages, certain characters can be visually joined when they're adjacent.

While written language and character are slightly less precise, they should be more familiar and less likely to cause misunderstandings.

Give useful context

Tell readers what you're expecting them to know up front—and provide links to where they can learn it if you can. See the Get started: optimize your React app post for an example. Make sure readers won't get lost when you link them off to other sites. In other words, make sure there's a clear connection between your content and the linked content.

Explain why what you're teaching matters before jumping into the instruction. This context can be provided in a collection via an introductory post (see the Accessible to all collection for an example) or in a post via an introductory paragraph (the Use Imagemin to compress images post is a nice example).

Indicate which details are relevant in longer code blocks by providing explanations and code highlighting. If readers don't need to understand everything about the code, tell them that—it makes the task less intimidating, especially for less experienced developers. See the Serve responsive images post for an example.

When there's more than one way to solve a problem, organize them in order of simplest to most complex.

Make section headings scannable

Canonical example: Performance budgets 101

A lot of web.dev readers are in a hurry. Putting a lot of thought into how you word your section headings makes your content much more usable for readers who need to quickly find certain information.

Alignment to larger priorities

Write in the web.dev voice as much as possible

Canonical example: Serve images with correct dimensions suggests multiple approaches in a friendly, positive way]

Whenever a reader comes to web.dev, we want them to expect a voice that is knowledgeable, humble, sympathetic, and friendly.

Follow our style guides

web.dev primarily follows the Google Developer Documentation Style Guide (GDDSG). Exceptions to the GDDSG are listed in the handbook. Adherence to the style guides is important for conveying a sense of professionalism to repeat visitors.

web.dev authors aren't expected to memorize every style guide rule. The best approach is to give your web.dev reviewer edit access to your article and let them do a final pass on the content to adhere to our style guides. They won't make any changes that substantially affect your voice.

Engaging UX

Think about whether there's a better medium to express your ideas

Canonical example: How to prevent clickjacking uses a drawing to effectively convey an idea that's hard to describe in text and Are long JavaScript tasks delaying your Time to Interactive? uses DevTools performance recordings to visualize long tasks

Aside from breaking up long sections of prose, media can be better than text for conveying some concepts and instructions. A key question to ask as you write is: "Is there a better way to express this idea?"

web.dev supports the following figures, which you can include in your post or codelab by following the examples in the web.dev components post.

Use high-quality media

Nobody likes a blurry photo!

Last updated: Improve article