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.

There may also be contexts in which we're talking about third-party tools or products (a library for a particular language, say, or a useful and relevant utility); there again, it's fine to link to the relevant site.

But 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:

Use an external link icon to indicate that the link opens in a new window or tab.