Best practices for linking to third-party websites

Splunk documentation sometimes has links to pages outside of the documentation or a Splunk website. When you include a link to a page outside of a Splunk site, consider whether the link is essential for the reader or if it's supplemental information.

Essential links

An essential link is a link in the documentation that brings a reader to information they might have difficulty locating on their own but need to access while reading the topic. Linking to an outside website is sometimes necessary, such as in these cases:

• You're sending a developer to a third-party code repository.
• You're sending a reader to a third-party documentation site that has task information about connecting their product to a Splunk app or add-on.
• You're linking to a guided setup in a Splunk product portal.

When you need to provide a link outside of Splunk documentation, follow these guidelines:

• Spell out the full URL.
• Include "http://www" or "https://www" in the URL.
• Don't capitalize any letters in the URL.
• Remove the trailing slash at the end of the URL.
• Third-party links can change without notice, so check that the links work with every release of your documentation.

See the following table for examples of how to format links to essential third-party pages:

Do this	Don't do this
You must create your own Slack app and add it to your workspace. See https://api.slack.com/messaging/webhooks in the Slack API.	You must create your own Slack app and add it to your workspace. See the Slack API docs.
Install the fluent-plugin-systemd plugin for systemd journal log collection. See https://github.com/fluent-plugin-systemd/fluent-plugin-systemd/blob/master/README.md on GitHub.	Install the fluent-plugin-systemd plugin for systemd journal log collection.
Create a Splunk On-Call webhook by following the steps in https://help.victorops.com/knowledge-base/rest-endpoint-integration-guide.	Create a Splunk On-Call webhook.

Supplemental links

A supplemental link is a link in the documentation that brings a reader to information they can locate on their own through an internet search. Avoid creating deep links to pages outside of Splunk sites when the link is supplemental. Instead, consider other ways you can direct users to information if you think they need assistance finding it, such as giving the user a search term and a website name.

See the following table for examples of guiding readers to searchable supplementary information without sending them away:

Do this	Don't do this
Search for "Query tables" on the Microsoft website.	Go to https://learn.microsoft.com/en-us/office/vba/api/excel.querytable.
For details, see "Setting up a Remote WMI Connection" on the Microsoft website.	See https://learn.microsoft.com/en-us/windows/win32/wmisdk/connecting-to-wmi-remotely-starting-with-vista.