Whenever possible, include hyperlinks where relevant within the text itself. Avoid creating lists of doc links in the For more help section, because it is harder for future writers to determine why they matter.
If you're linking to the product, see our style guide page on UI paths.
Follow these guidelines when writing text for hyperlinks:
- Labels: Make sure each link in the document has a unique, meaningful text label. Do not use the same text string to label different links.
- Location: Include a clear, concise text label to identify where the link goes. Give extra context if you're linking to an external site. Why are you sending someone there?
- Click here: Do not use "click here" or other meaningless link labels.
- "Link test:" Read just the links, without the surrounding text. Can each stand alone as a clear description of where the link goes if that is all the user looks at on the page?
- Avoid URL prefixes: If you're sending users to an address where you want to use the URL as the link text, drop the
www.prefixes from the link text. For example,
Take the link test for these three examples. The last is the best for readers looking for information on configuring PHP, because the link clearly identifies it, without having to read anything else on the page.
"Link test" example
To learn more about renaming your PHP app, click here.
To learn more about renaming your PHP app, see New Relic's config docs.
To learn more about renaming your PHP app, use the PHP agent (newrelic.ini) settings.
Never include a hyperlink to the Support email address. This prevents spam and ensures customers use the ticket submission form to create tickets so they receive the correct support priority. If you need to tell customers to contact support, use this instead:
Get support at [support.newrelic.com](support.newrelic.com).
Docs site ("internal") links
When creating links to other documents on the docs site, include only the path from
/docs forward. Do not include
https://docs.newrelic.com, or the site will treat it as an external link.
Here is an example:
[/docs/agents/php-agent/configuration/php-agent-newrelic-ini-settings](PHP agent (newrelic.ini) settings
If your link includes an anchor (for example,
#inivar-scope), use the complete, current doc path it uses. Some browsers do not retain anchors with redirects.
When creating or editing an HTML
id for an anchor link, follow these guidelines:
- Only use lower case when creating new IDs.
- Use hyphens
-to separate words. Don't use
- When reorganizing a doc, try to preserve incoming anchor links where possible. Be mindful that when you delete a level two heading
##, it will break any links to that heading.
- Avoid changing an existing anchor ID, because we may be monitoring traffic to it from our internal New Relic account.
Deep links into product
When directing users to parts of the product, you want to deep link when possible. Deep linking encourages users to go into the product and, if they haven't created an account yet, prompts them to sign up. This is more effective than just linking to a sign up page. However, deep linking into the UI only works sometimes and it takes some experimenting to find a good permalink.
Here's an example workflow using the Logs UI:
- From your work account, go to the part of the UI you want to link. Grab the complete URL as it appears naturally.
- Open an incognito window and paste in the URL.
- Edit the URL to a cleaner state. We want simple URLs when possible. For logs, this looks like this:
- New Relic will prompt you to sign in, so sign in with a non-work email.
The URL sends you to the logs page and auto-completes account ID identifying information. That page is deep linkable.
If the simple URL doesn't work, you have two extra steps. Here's an example workflow where the simple URL doesn't work. We'll use this URL to work off of:
- After finding your URL, open an incognito window and paste in the simple URL:
https://one.newrelic.com/marketplace/install-data-sourceThis page doesn't load with the simplified URL.
- Test this URL by removing the
account=[ACCOUNT_ID_HERE]part of the slug. The new URL will look like this:
- Paste that URL in a new incognito window. It'll take you to the correct page with your unique account ID populated in.
- Confirm with another writer that this URL works by having them open the URL with the account ID number removed. They should use a non-work email.
If the URL fails in either case, it's likely that that part of the product UI is not deep linkable. In that case, link
one.newrelic.com to the All capabilities page, then describe the path per our pathing guidelines.
When creating links to websites outside the
docs.newrelic.com subdomain (including
discuss.newrelic.com), the docs site automatically includes code that opens the link in a new tab.
In addition to the link text guidelines in this doc, here are some other things to keep in mind when linking to external sites:
- Think about the best way to future-proof your links. If possible, point to a top-level domain, but not if it reduces the usefulness of the link. How stable is the content you're linking to? Is the URL likely to change?
- Make sure your link is as useful as possible. What value are you trying to add to the document? Can that information be shared in another way?
- Help the reader understand why you're linking to this external source. Is it a useful reference, such as a list of time zones? Is it a way to save someone time, such as linking directly to a hard-to-find file?
- Make sure that your link is generally accessible. Are you linking to an external site that requires authentication, such as a private GitHub repo?
Linking to an arbitrary (non-heading, non-collapser-entry) section in a doc
H2 and H3 headings and collapsers have their own built-in IDs that you can link to. But sometimes you may want to link to a paragraph or to a table entry. In general, avoid this, and instead, link to headings and collapsers.
Occasionally it's useful to link to a specific entry in a table, or a very important paragraph in a conceptual explanation. To do that, place a
<span> tag around some text, using this format:
<span id="name">your text</span>
And then link to it using the standard anchor link format.