Best practices for including links

Good linking provides access to related material without diverting the reader from the focus of the topic they are in. If related topics add value to your content, consider linking to them at the end of the topic. It's less common to link in the middle of task steps or paragraphs, so consider the reader experience before you add an inline link in your content.

Before you add a link

Before adding links into your content, consider these best practices:

• Don't include links in the first paragraph of a topic.
• Provide critical information in your topic, not in linked information.
• Weigh any cost of including a link, such as distraction or confusion to the reader, against the benefits.
• If the content unit you want to link to is small, consider reusing the content rather than linking away to it.
• Use links in notes, cautions, or troubleshooting substeps only if it helps the reader complete the task or helps them get unstuck.

Where to include links

You can add links either inline in your content or at the end of a topic in their own section. In most cases, include related links at the end of your topic.

Add your link to the end of the topic if it's this type of information:

• A related supplementary resource
• A next step

Add your link inline in your topic if it's this type of information:

• An essential prerequisite or component to a task
• A troubleshooting resource in a task substep

Guidelines for including links

If you decide to add a link inline in your content, follow these best practices:

• Give readers adequate context to decide if it's a link they want to follow. Don't hide a link behind words or actions in a sentence without stating what the link is.
• In most cases, use the word "See" to introduce a link in the sentence or clause.
• Use the exact topic title or section heading, page name, or entity name you are linking to for the link text. Don't paraphrase the linked-to topic title or name.
• Avoid linking to a subheading in a different topic. Strive to link to the top-level heading of the page to avoid links breaking.
• Keep punctuation that isn't part of the title outside the hyperlink.

See the following examples of how to present inline links:

Do this	Don't do this
See Get Windows Data into Splunk Cloud Platform.	Next, get Windows data in.
Find a summary of the latest updates and changes at What's new on the Splunk Developer Portal for Splunk Cloud Platform and Splunk Enterprise.	Find a summary of the latest updates and changes.

Related links

• For more information on formatting links, see Formatting links in Splunk documentation.
• For information on linking in the UI, see Links in the UI text style guidelines topic.