[docs] [workflows] Improve docs for linking to Gatsby and non-Gatsby content

[prestonso]

Part of the Top 25 Learning Workflows initiative. See #13708 for the meta issue that this issue falls under.

User story

As a new Gatsby user, I want to understand the difference between <Link> and <a> and successfully link internally and externally.

Evaluation

Search	Discover	Complete	Linked	Tone	Style	Overall
😄	😐	😐	😄	😄	😄	😄

Steps taken to implement

1. Searchability
   1. Searched gatsby linking pages on Google; clicked first result.
2. Discoverability
   1. Searched gatsby linking pages in search bar; all listed results take user to The Gatsby Link component (anchor link, though main page is second result).
   2. Clickpath on .org:
      1. Clicked Docs.
      2. Clicked Guides. Nothing there. [rec] (from @marcysutton) Move the guide up in the list of the current subsection, since it's a key workflow.
      3. Clicked Recipes. Aha! Linking between pages. But this heading isn't the same as the previous "Linking between pages" page.
      4. Result: [rec] We have three different pages dedicated to linking between pages; four if you include the Gatsby API page on <Link>. Deduplicate or disambiguate:
         • Linking between pages (this is the desired page)
         • Recipe: Linking between pages (not enough information)
         • Tutorial: Linking between pages (undiscoverable unless following tutorial)
3. Completeness
   1. Followed steps in The Gatsby Link component. Immediately indicates the difference between internal and external linking.
      1. [rec] Add information about rel="noopener noreferrer" right here.
   2. Followed steps in Using the <Link /> component. Very simple example that gets me up to speed. Less comprehensive than the tutorial page.
      1. [rec] As a new developer, I may not have easily understood from this docs page that e.g. <Link to="/"> is possible (homepage link). Add a note with this information.
      2. [rec] As a new developer, I may not have easily understood from this docs page that import { Link } from "gatsby" is so important. Add a note emphasizing this.
4. Linkedness
   1. Good, but link to Tutorial: Linking between pages in "Other resources" section interrupts my flow and places me into a tutorial that I may not have the immediate context for.
      1. (Note from @marcysutton) The sentence leads with "For the complete example..." perhaps it could list a recipe first and then offer the tutorial as more of a step-by-step guide so people are more prepared for it.
5. Tone
   1. Good
6. Style
   1. Good

Recommendations

• (from @marcysutton) Linking between pages: Move the guide up in the list of the current subsection, since it's a key workflow.
• We have three different pages dedicated to linking between pages; four if you include the Gatsby API page on <Link>. Deduplicate or disambiguate:
  • Linking between pages (this is the desired page)
  • Recipe: Linking between pages (not enough information)
  • Tutorial: Linking between pages (undiscoverable unless following tutorial)
• The Gatsby Link component: Add information about rel="noopener noreferrer" right here.
• Using the <Link /> component: As a new developer, I may not have easily understood from this docs page that e.g. <Link to="/"> is possible (homepage link). Add a note with this information.
• Using the <Link /> component: As a new developer, I may not have easily understood from this docs page that import { Link } from "gatsby" is so important. Add a note emphasizing this.

[marcysutton]

We have three different pages dedicated to linking between pages; four if you include the Gatsby API page on . Deduplicate or disambiguate:

• Linking between pages (this is the desired page)
• Recipe: Linking between pages (not enough information)
• Tutorial: Linking between pages (undiscoverable unless following tutorial)

The biggest confusion I've found with duplicated content is that the format is similar, and you can't easily tell where you are in the docs IA. With a few improvements, I think duplicated content will be more helpful than confusing. These are the changes I have in mind:

• Recipes with a concise, repeatable format including pre-reqs and actionable content instead of links elsewhere (see docs IA proposal)
• Docs breadcrumbs (in progress in [docs] Breadcrumbs for all docs pages #13475)

I think it's less important that the tutorial content be discoverable outside of the guided flow...that is more of a job for the recipe and reference guide content.

We could play with page titles, but beyond improving recipes I'm open to ideas @prestonso

[prestonso]

Closing as #14036 is now merged.