Linking to other sites

For example, 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 may be able to assume that readers already know about it, and may remove those brief explanations.

Another example: if you want to mention one HTTP status code, then describing it in your document may 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) may 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.

Enviar comentarios sobre…

Google Developer Documentation Style Guide
Google Developer Documentation Style Guide