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 documentation has 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 that any site that 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, in general, remove it. Many sites will then redirect to a version of the site that matches the user's browser locale setting. However, note the following:
- Test the links that you remove the locale information from. In some cases, the locale indicator is a necessary part of the URL, so you might need to restore it.
- If the link is to Wikipedia
(for example,
https://en.wikipedia.org/wiki/Operating-system-level_virtualization), then leave the locale indicator (en.in the example). Many Wikipedia articles don't exist in other languages, and even if they do, they aren't necessarily translations. Keeping the locale indicator guarantees that the link will work and that it goes to the article you intend.
Don't force links to open in a new tab or window. Let the reader decide how to open links.
In the rare situation that a link needs to open in a new tab or window, let the reader know that the link opens differently than expected.
Recommended:
<a href="/style/accessibility" target="_blank">Accessible content (opens in a new tab)</a>
Not recommended:
<a href="/style/accessibility" target="_blank">Accessible content</a>
Don't use an external link icon to indicate that the link goes to a different domain or server. If you think it's important to inform the reader that they're leaving a Google domain, mention it in the text and don't rely on an icon.
Recommended:
For more information, see OS-level virtualization.
Sometimes OK:
For more information, see the Wikipedia page about OS-level virtualization.
Not recommended:
For more information, see OS-level virtualization.
In a documentation set's navigation, such as a table of contents, don't link outside of the documentation set. If it's important to link to documentation that isn't contained within the current documentation set, include the link in a page within the documentation.