Our fourth and final SEO experiment for MDN, to optimize internal links within the open web documentation, is now finished. Optimizing internal links involves ensuring that each page (in particular, the ones we want to improve search engine results page (SERP) positions for, are easy to find.

This is done by ensuring that each page is linked to from as many topically relevant pages as possible. In addition, it should in turn link outward to other relevant pages. The more quality links we have among related pages, the better our position is likely to be. The object, from a user’s perspective, is to ensure that even if the first page they find doesn’t answer their question, it will link to a page that does (or at least might help them find the right one).

Creating links on MDN is technically pretty easy. There are several ways to do it, including:

• Selecting the text to turn into a link and using the toolbar’s “add link” button
• Using the “add link” hotkey (Ctrl-K or Cmd-K)
• Any one of a large number of macros that generate properly-formatted links automatically, such as the domxref macro, which creates a link to a page within the MDN API reference; for example: {{domxref(“RTCPeerConnection.createOffer()”)}} creates a link to https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection/createOffer, which looks like this: RTCPeerConnection.createOffer(). Many of the macros offer customization options, but the default is usually acceptable and is almost always better than trying to hand-make the links.

Our style guide talks about where links should be used. We even have a guide to creating links on MDN that covers the most common ways to do so. Start with these guidelines.

The content updates

10 pages were selected for the internal link optimization experiment.

Changes made to the selected pages

In general, the changes made were only to add links to pages; sometimes content had to be added to accomplish this but ideally the changes were relatively small.

• Existing text that should have been a link but was not, such as mentions of terms that need definition, concepts for which pages exist that should have been linked to, were turned into links.
• The uses of API names, element names, attributes, CSS properties, SVG element names, and so forth were turned into links when either first used in a section or if a number of paragraphs had elapsed since they were last a link. While repeated links to the same page don’t count, this is good practice for usability purposes.
• Any phrase for which a more in-depth explanation is available was turned into a link.
• Links to related concepts or topics were added where appropriate; for example, on the article about HTMLFormElement.elements, a note is provided with a link to the related Document.forms property.
• Links to related functions or HTML elements or whatever were added.
• The “See also” section was reviewed and updated to include appropriate related content.

Changes made to targeted pages

Targeted pages—pages to which links were added—in some cases got smaller changes made, such as the addition of a link back to the original page, and in some cases new links were added to other relevant content if the pages were particularly in need of help.

Pages to be updated

The pages selected to be updated for this experiment:

• https://developer.mozilla.org/en-US/docs/Web/CSS/object-position
• https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/HTML_in_XMLHttpRequest
• https://developer.mozilla.org/en-US/docs/Web/API/Document_object_model/Locating_DOM_elements_using_selectors
• https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices
• https://developer.mozilla.org/en-US/docs/Web/API/HTMLFormElement/elements
• https://developer.mozilla.org/en-US/docs/Web/API/XMLSerializer
• https://developer.mozilla.org/en-US/docs/Web/CSS/all
• https://developer.mozilla.org/en-US/docs/Web/API/HTMLCollection/item
• https://developer.mozilla.org/en-US/docs/Web/CSS/inherit
• https://developer.mozilla.org/en-US/docs/Web/CSS/unset

The results

The initial data was taken during the four weeks from December 29, 2017 through January 25th, 2018. The “after” data was taken just over a month after the work was completed, covering the period of March 6 through April 2, 2018.

The results from this experiment were fascinating. Of all of the SEO experiments we’ve done, the results of this one were the most consistently positive.

Landing Page	Unique Pageviews	Organic Searches	Entrances	Hits
/en-us/docs/web/api/document_object_model/locating_dom_elements_using_selectors	+51.44%	+27.89%	+34.08%	+65.62%
/en-us/docs/web/api/htmlcollection/item	+62.29%	+48.44%	+64.81%	+46.97%
/en-us/docs/web/api/htmlformelement/elements	+77.59%	+63.75%	+76.83%	+78.34%
/en-us/docs/web/api/mediadevices/enumeratedevices	+27.84%	+15.88%	+21.05%	+20.48%
/en-us/docs/web/api/xmlhttprequest/html_in_xmlhttprequest	+53.52%	-1.43%	+27.79%	+63.51%
/en-us/docs/web/api/xmlserializer	+40.08%	+53.19%	+35.94%	+42.64%
/en-us/docs/web/css/all	+53.92%	+27.62%	+31.11%	+54.90%
/en-us/docs/web/css/inherit	+26.05%	+30.79%	+24.71%	+19.94%
/en-us/docs/web/css/object-position	+111.77%	+128.45%	+116.12%	+426.94%
/en-us/docs/web/css/unset	+30.09%	+23.03%	+23.93%	+41.01%

These results are amazing. Every single value is up, with the sole exception of a small decline in organic search views (that is, appearances in Google search result lists) for the article “HTML in XMLHttpRequest.” Most values are up substantially, with many being impressively improved.

Uncertainties

Due to the implementation of the experiment and certain timing issues, there are uncertainties surrounding these results. Those include:

• Ideally, much more time would have elapsed between completing the changes and collecting final data.
• The experiment began during the winter holiday season, when overall site usage is at a low point.
• There was overall site growth of MDN traffic over the time this experiment was underway.

Decisions

Certain conclusions can be reached:

1. The degree to which internal link improvements benefited traffic to these pages can’t be ignored, even after factoring in the uncertainties. This is easily the most benefit we got from any experiment, and on top of that, the amount of work required was often much lower. This should be a high priority portion of our SEO plans.
2. The MDN meta-documentation will be further improved to enhance recommendations around linking among pages on MDN.
3. We should consider enhancements to macros used to build links to make them easier to use, especially in cases where we commonly have to override default behavior to get the desired output. Simplifying the use of macros to create links will make linking faster and easier and therefore more common.
4. We’ll re-evaluate the data after more time has passed to ensure the results are correct.

Discussion?

If you’d like to comment on this, or ask questions about the results or the work involved in making these changes, please feel free to follow up or comment on the thread I’ve created on our Discourse forum.

https://www.bitstampede.com/2018/04/05/mdn-internal-link-experiment/