How to write with SEO in mind on MDN Web Docs

While the primary goal of any writing on MDN should always be to explain and inform about open web technology so developers can quickly learn to do what they want, or to find the little details they need to know in order to perfect their code, it's important that they be able to find the material we write. Since most readers reach content on MDN through search engines, as writers, we have to keep that in mind while creating the documentation on MDN. This guide covers our standard practices, recommendations, and requirements for content to help ensure that search engines can easily categorize and index our material in order to ensure that users can easily reach what they need.

Document status

We're currently in the midst of the early stages of what is intended to be a large-scale project to improve search engine optimization (SEO) on MDN. Before the work can truly begin, we're doing a number of small-scale experiments to try various ideas to see how they work out. As we pull together recommendations and ideas, they'll be getting added to this document.

You should expect that this article will be a bit of a "dumping ground" for a while, where initial notes are listed in brief for the time being, with more thorough guidelines being written once we have more confirmation of the usefulness of each of the ideas, as well as the overall scope of the work to be done.

Ensure pages aren't too similar

Each article should be as unique as possible. Articles that look similar to one another textually will wind up being considered to be about roughly the same thing, even if they aren't. For example, if an interface has the properties width and height, it's easy for the text to be surprisingly similar, with just a few words swapped out, and using the same example. This makes it hard for search engines to know which is which, and they wind up sharing page rank, resulting in both being harder to find than they ought to be.

Understandably, writers confronted with two related properties like width and height (or any other set of functionally related features) are tempted to write the article on width, then copy that article and paste it into the one on height, replacing a few words. Done!

Unfortunately, the result is two pages that, as far as search engines are concerned, may as well be the same thing.

It's important, then, to ensure that every page has its own content. Here are some suggestions to help you accomplish that:

  • Consider use cases where there might be more differences than one would think. For instance, in the case of width and height, perhaps consider ways horizontal space and vertical space are used differently, and provide a discussion about the appropriate concepts. Perhaps you mention the use of width in terms of making room for a sidebar, while using height to handle vertical scrolling or footers or similar.
  • Use entirely different examples on each page. Examples in these situations are often even more similar than the body text, since the examples may use both (or all) of the similar methods or properties to begin with, thereby requiring no real changes when reused. So throw out the example and write a new one, or at least provide multiple examples, with at least some of them different.
  • Include descriptions of each example. Both an overview of what the example does as well as coverage of how it works, in an appropriate level of detail given the complexity of the topic and the target audience, should be included.

The easiest way to avoid being overly similar is of course to write each article from scratch if time allows.

Avoid pages that are too short

Articles that are too short (called "thin pages" in SEO parlance) are difficult to catalog accurately. Whenever possible, pages on MDN should avoid being shorter than around 300 words or so. Here are some basic guidelines to help you create pages that have enough content to be properly searchable without resorting to cluttering them up with unnecessary cruft.

  • Keep an eye on the convenient word counter located in the top-right corner of the editor's toolbar on MDN. This is not an exact representation of the true word count, since the true word count is based on the rendered page, not the page as you see it in the editor. That means macros that add a lot of words will result in a higher word count, while macros that insert nothing but adjust formatting will result in a lower word count.
  • Obviously, if the article is a stub, or is missing material, add it. We try to avoid outright "stub" pages on MDN, although they do exist, but there are plenty of pages that are missing large portions of their content.
  • Generally review the page to ensure that it's structured properly for the type of page it is. Be sure every section that it should have is present and has appropriate content.
  • Make sure every section is complete and up-to-date, with no information missing. Are all parameters listed and explained?
  • Be sure everything is fully fleshed-out. It's easy to give a quick explanation of something, but make sure that all the nuances are covered. Are there special cases? Known restrictions that the reader might need to know about?
  • There should be examples covering all parameters or at least common sets of parameters. Each example should be preceded with an overview of what the example will do, what additional knowledge might be needed to understand it, and so forth. After the example (or interspersed among pieces of the example) should be text explaining how the code works. Don't skimp on the details and the handling of errors in examples; readers will copy and paste your example to use in their own projects, and your code will wind up used on production sites! See Code examples and our Code sample guidelines for more useful information.
  • If there are particularly common use cases for the feature being described, talk about them! Instead of assuming the reader will figure out that the method being documented can be used to solve a common development problem, actually add a section with an example and text explaining how the example works.
  • Include proper alt text on all images and diagrams; this text counts, as do captions on tables and other figures.
  • Do not descend into adding repetitive, unhelpful material or blobs of keywords, in an attempt to improve the page's size and search ranking. This does more harm than good, both to content readability and to our search results.

See also

Document Tags and Contributors

 Contributors to this page: Sheppy, Havvy
 Last updated by: Sheppy,