Linking to other sites

Our documentation often relies on the reader knowing something about third-party standards or software. In such cases, it's better to link to good documentation elsewhere than to try to thoroughly document someone else's standard in our documentation.

On the other hand, sometimes a few sentences of basic information can save readers a trip to an external site. For example, our API docsets have traditionally included a brief explanation of REST. As knowledge of REST becomes more widespread, we might be able to assume that readers already know about it, and can remove those brief explanations.

Another example: If you want to mention one HTTP status code, then describing it in your document might make sense. If you want to make sure that your reader understands the idea of HTTP status codes, and knows what several of them mean, then linking them to an external document (such as the HTTP spec) might be a good idea.

In some cases, you might discuss third-party tools or products (a library for a particular language, say, or a relevant utility); in such cases, it's okay to link to a relevant site.

Make sure any site you link to is high quality, reliable, and respectable.

Link to the most relevant page on a site. Link to the most relevant heading on a page.

If the URL has a locale indicator, remove it and then test the link. For example, in a Wikipedia link, change the following:

to this:

Don't force links to open in a new tab or window. Let the reader decide how to open links. If you think a link needs to open in a new tab or window, let the reader know that the link is opening differently than expected. For example, if the following link opens in a new tab, the link text should let them know: Accessible content (opens in a new tab).

Use an external link icon to indicate that the link goes to a different domain or server. For more information, see Cross references.