web.dev content review checklists

This page contains the official checklists that all web.dev editors are expected to use when reviewing new content. Authors are encouraged to use these checklists to self-review their writing and fix problems proactively, rather than waiting for an editor to catch them.

The review process has two parts. The goal of the early stage review checklist is to make sure the content is useful to web.dev's target audience. The goal of the late-stage review checklist is to make sure the content is professional and "plays nicely" with the rest of the web.dev codebase (e.g. not using a URL that we'll want to use for other purposes).

Early stage review checklist #

The content aligns with web.dev's main audience #

web.dev's mission is to help web developers build excellent websites. All content on web.dev should help web developers in one way or another. If the content does not seem helpful for web developers, or the content seems to be primarily written for an audience other than web developers, it's probably not a good fit for web.dev.

The content is about techniques or APIs that are available cross-browser #

If the content is about an API in origin trial, or only available in Chrome, it is likely that developer.chrome.com is the better location.

The guidance is usable #

If the content provides step-by-step instructions on completing a task, make sure that someone (other than the author) has actually followed the instructions and was able to complete the task successfully. The editor can do this themselves or ask the author to find someone else to do a usability review.

See Usability reviews for instructions.

The content is a tutorial, how-to guide, or explainer #

There are four common types of software documentation: tutorials, how-to guides, explainers, and references. Check out Divio's Documentation System for an explanation of these content types.

Each page of web.dev content should be focused around one of these content types as much as possible. For example, a single page of content should not try to be a tutorial and an explainer.

Reference documentation pages are not allowed on web.dev. Reference documentation is better suited for MDN, or our web platform documentation section.

The content is unique #

After reading through the content, use a search engine to search for similar content (from any reputable source, such as MDN or CSS-Tricks). If the proposed web.dev content largely duplicates another source's content, ask the author why it's necessary to duplicate the content.

The content is focused on a main idea #

Each page of content should have a main idea. All text, images, videos, code samples, etc. should be related to the page's main idea.

The content provides a path for getting background knowledge #

Think about the background knowledge that's required to understand the content you're reviewing. The content should provide a well-lit path for gaining that background knowledge.

Here are the common strategies for helping readers gain background knowledge:

• Expand the content to explain the topic in more depth.
• Link to other, existing content on the topic.

The one exception to this rule is basic web development knowledge. web.dev assumes that its readers understand the basics of CSS, HTML, and JavaScript.

Factual information is verified #

Factual claims should be backed by evidence or authoritative sources as much as possible.

One seemingly small factual claim that has caused trouble in the past was the browser version associated to an API's release. For example, a post might claim that an API is launching in Chrome 88, but the author and reviewer didn't double-check that claim. A lot of web developers might then see the announcement on web.dev, attempt to try out the API, and get confused when the API doesn't work as intended (because it's not actually supported in that version).

The guidance is aligned with best practices #

Make a best effort to ensure that the content is aligned with general web development best practices.

Here are some strategies for checking if the content is aligned with best practices:

• Run Lighthouse regularly and review all of its recommendations. Check if the content you're reviewing contradicts any of Lighthouse's recommendations.
• If the content discusses different aspects of web development (e.g. accessibility and performance) and the author is only an expert in one of those aspects (e.g. performance), ask a subject matter expert (SME) to do a quick review of the content. Instruct the reviewer to specifically focus on making sure that the content is aligned with the best practices of their area.

Here are some common problems:

• Using outdated Lighthouse metrics. The page should explicitly mention that the metric is outdated, and list its recommended replacement.
• The unload event is considered harmful. The pagehide event should be used instead.

Anti-patterns should be clearly labeled #

Bad web development practices should clearly be labeled as such. Consider using caution or warning components.

Avoid subjective statements like "it's easy" #

Subjective statements like "it's easy" or "the process is simple" can usually be removed. What might be easy for some might not be easy for others. Take a look at the Words to Avoid in Educational Writing post from css-tricks for other examples.

Avoid summaries at the end of the content #

The intro of the page should already summarize the content.

The writing is simple #

Use the simplest words available unless there is a specific reason to use a fancy word.

See also Avoid fancy words.

Avoid using cultural idioms, for example: "Kill two birds with one stone". These may not be familiar to all readers.

The writing is concise #

The writing should be as long as needed in order to effectively explain the main idea of the page, and no longer.

All words are necessary #

Delete redundant words, sentences, paragraphs, sections, and so on.

One exception is when the author intentionally repeats an idea to make it easier to understand or emphasize its importance.

The writing uses the present tense by default #

Rephrasing a text from the future tense to the present tense usually removes tens or hundreds of words from a text, without changing the meaning.

The author can use the future tense if they provide a logical rationale for its need.

The title is optimized #

All web.dev titles should include all of the following elements whenever relevant:

• A general description of the use case that the content helps solve
• The exact name of the most relevant API, tool, product, etc.

The intro clearly summarizes the purpose of the page #

Explicitly summarize what "task" you help the user solve in your intro. The "task" might be something concrete, such as optimizing images, or something abstract, such as understanding how browsers work. The first or last sentence of the intro is usually a good place for the summary. Consider using the objective component.

Here is a general formula for creating a useful summary:

• Mention the content type of the page: tutorial, how-to guide, reference, overview, etc. Mentioning the content type gives the reader a general idea of what type of content to expect.
• Mention the user-focused task that the page helps solve.

Examples:

• Extending Workbox
• Workers overview
• Building a Stories component
• Browser-level lazy loading for CMSs
• Measuring offline usage

Note that some of these examples use the generic term "post" or "article". They could be improved by replacing "post" or "article" with a more specific content type keyword, like guide, tutorial, etc.

The subheading (subtitle) draws the reader in or provides more context #

See subhead: add an enticing subtitle.

The content is easy to scan #

Many web.dev readers are in a hurry. All web.dev content should be easy to scan.

Section headings are concise and descriptive #

Each section heading should clearly summarize the content contained within that section.

Similar ideas are grouped together #

Scan the sections of the content. Check for sections with similar ideas that are placed far apart (e.g. one section is at the top of the article, the other is at the bottom, yet they both discuss related concepts).

Here are some common problems:

• The page concludes with a Frequently Answered Questions (FAQs) section. Check if the FAQs can be contextually discussed within a main section of the content. See also FAQs are a code smell.

The paragraphs are effective #

Each paragraph should be focused around one idea. The first sentence summarizes the main idea of the sentence. The following sentences provide supporting details of the main idea. The last sentence concludes the idea or transitions to a new idea. See Writing Effective Paragraphs.

Complex ideas are explained effectively #

While reading a page, notice if you have to stop and re-read a section multiple times before you understand what it's saying. Check if any of the following strategies can be used to explain the idea more effectively:

• Images and videos
• Examples

Browser compatibility is mentioned near the start of the content #

When content is focused around specific web platform features or APIs, make sure that the browser compatibility of the APIs is specifically mentioned by including the BrowserCompat component.

If a solid polyfill is available to complete support in all three engines, include details along with the BrowserCompat component.

If the post refers to a number of APIs, or CSS properties, add the component for those features near the first mention of them.

If the post mentions an API that is supported by all major modern browser engines without a polyfill, include the BrowserCompat component to clearly communicate that fact.

Example: New to the web platform in May.

References to APIs link to relevant MDN documentation #

When referencing a specific web platform API, link to the MDN reference documentation page for that API.

Code samples are minimal, complete, and reproducible #

Any code that is not directly relevant or necessary for understanding the main idea of the code sample should be deleted.

See also How to create a minimal, reproducible example.

Links are useful #

For each link that the author provides, look out for:

• A mismatch between the link text and the content of the link. For example, suppose that the link text is service worker tutorial but the content of the link is actually an API reference documentation page.
• Content that does not actually help the reader.

The content references specific versions of browsers, not release channels #

The release channels of major browsers are not stable over time. For example, currently Google Chrome Stable refers to version 85 of the browser. In a year, Google Chrome Stable will refer to version 95.

Other people's products are used as intended #

If the content mentions or features other people's products, said products are to be used as intended. For example, an article should not advise to flash a "homebrew" firmware onto a commercial device, unless this is explicitly blessed by the manufacturer.

Use examples liberally #

Provide more examples if a concept is unclear.

Get permission before mentioning other companies, products, etc. #

Don't mention other companies, products, services, etc. without that entity's permission. You can ask the content lead to make exceptions to this rule, which will be done on a case-by-case basis.

Use inclusive language #

Refer to the GDDSG word list and make sure that you're not using any insensitive words, such as:

• blacklist
• whitelist
• native
• grandfathered
• hang
• master
• slave

Refer to the Inclusion and accessibility section of the handbook to verify that text is inclusive for all audience members.

Late-stage review checklist #

Titles and section headings are sentence case #

Follow the Google Developer Documentation Style Guide's guidance on titles and headings.

The URL mostly matches the title and is not overly general #

The URL of a page of content should mostly match the title of that page of content to avoid confusion.

The URL of a page should not be overly general, unless that page is our authoritative content on that topic. For example, the URL of Introducing <model-viewer> 1.1 is https://web.dev/introducing-model-viewer/ because we wanted to reserve https://web.dev/model-viewer/ for our authoritative guide on that topic.

The page uses components when relevant #

Review web.dev's UI components and check if the presentation of any of the content can be enhanced by the components.

The hero image's thumbnail looks good #

If the page is going to be on the blog and has a hero image, go to the blog index page (e.g. http://localhost:8080/blog if you're reviewing the content locally) and make sure that the thumbnail version of the hero image looks good and is not cropped in a weird way. Use a thumbnail if necessary.

All images have descriptive alt text #

Review the Markdown and make sure that each image has descriptive alt text. Put yourself in the shoes of people who can't see those images. Is there any critical information embedded in the images that isn't covered anywhere else in the content?

All images use the Img shortcode and are sized correctly #

Images must use the {% Img %} shortcode and should contain width and height attributes.

![A system-level share target picker](./picker.png)

{% Img src="image/admin/cCXNoHbXAfkAQzTTuS0Z.png", alt="A system-level share target picker", width="370", height="349" %}

All words are spelled correctly #

Follow the Google Developer Documentation Style Guide's guidance on spelling.

The most important lines of code in a code block are highlighted #

Code highlighting should be used to indicate lines that have been added or changed.

GIFs have been converted to animated videos #

All GIFs should be converted to animated videos to improve performance. See Replace animated GIFs with videos and Videos hosted on web.dev