[docs][workflows] plugin authoring workflow improvements

[gillkyle]

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 how to build a plugin using Gatsby, and when I should use a plugin (vs a theme or starter).

Evaluation

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

Steps taken to implement

1. Searchability:

• Searching gatsby plugin brings up plugin library and docs first 👍
• anecdotally, searching gatsby themes or gatsby theme now ranks ahead of Great Gatsby related content 😅

2. Discoverability

• Very discoverable with the top nav including a link to the plugin library, also one of the first sections in the sidebar
• using the site searchbar finds "Creating a Plugin" by typing in plugin

3. Completeness:

The docs about plugins are quite complete,

Plugins:

• How plugins are used is answered in "Using a plugin..."
• Why plugins are used is answered in "What is a plugin?" and "What you don't need plugins for"
  • aren't a ton of use cases that would help clue in new users as to when plugins are appropriate, when you'd write your own, or when you'd make it a theme outside of the "What is a plugin?" doc or just perusing the plugin library
• cover more content in the Building a Source plugin guide (which should maybe be moved to the tutorials sections since it's called a tutorial) [docs][tutorial] building a source plugin tutorial #16095

Themes:

• the first paragraphs of the "Getting Started" page blur the lines between starters, themes, and what are dubbed by the doc theme starters and regular starters. I think this could be moved lower down in the page in favor of jumping into the steps
• illustrations could help explain tough ideas: see [docs][themes] Add visual aids to explain themes concept better in docs #15616

4. Linkedness

• Seems pretty well linked, there are a lot of docs on this and cross-linking them well is really helpful. Some of the plugin docs are old especially compared to theme docs, so making sure they each surface relevant content from the other sections would be great.

5. Tone

• The tone feels positive and fun, explanations could be a bit wordier to provide more context in places though

6. Style

• Conforms with the style guide 👍

Recommendations

• Plugin authoring overview (understanding/flowchart/diagrams)

• Add more use cases to guides in each section (ask why am I doing this at different steps) - an example for the plugins section: (docs: plugin authoring workflow overview pages #20847)

  • "Loading local plugins" why would I use a plugin in a plugins folder if I can just install one? This doc could explain why you might want your own local plugin without deploying to npm and link to the writing your own plugin doc
  • might make sense to add a page on contributing to a plugin and steps to fork and use it locally

• "Naming a Plugin" tweaks: (docs: plugin authoring workflow overview pages #20847)

  • "four standard...naming conventions" but 5 are listed
  • add example bullet point for gatsby-theme-*, and explain what the example plugin does in a few words
  • add a link to docs for creating a theme (which already exist) after an example is added in a bullet point - Docs: [creating a theme](https://www.gatsbyjs.org/docs/themes/building-themes/)

• make simple flowchart/table about when to use a plugin/theme/starter (docs: flowchart and tables for differences between plugins, themes, and starters #21659)

---

• Plugin tutorials/sample code

• flesh out content in the Pixabay source plugin tutorial [docs][tutorial] building a source plugin tutorial #16095 (maybe move it to tutorials section as well? it redirects to the tutorials section now Rename Theme tutorials to Plugin and Theme Tutorials and update redir… #21908)

  • foreign key relationships
  • setting plugin status
  • handling caching
  • linking and transforming nodes (these suggestions from issue [docs][tutorial] building a source plugin tutorial #16095)
  • some advanced use cases covered in the Cloud Preview docs

• should the new remark plugin be moved to the tutorials section as well? (Rename Theme tutorials to Plugin and Theme Tutorials and update redir… #21908)

• the Creating a source plugin guide is mostly text, could benefit from additional code blocks with sample code (maybe from existing plugins?)

• create a guide on using plugin options (docs: add new guide and example site on plugin options #21708)

---

• Contributing to/maintaining a plugin (covered in [docs] stub: Maintaining a Plugin #21067)

• remove stub for "Maintaining a plugin"

  • link to docs on versioning/publishing packages to npm (those seem covered by other docs already)

• pair with someone from Core to update How APIS/Plugins are Run

---

Pausing on theme related docs for now

• Theme Authoring

• simplify naming terminology of "Getting Started" doc's introduction (see rationale in notes above)

• to help explain differences create a flow chart on when to use a starter, theme, or plugin (see card)

• "When should I use or build a theme?" could explain how themes can use multiple plugins together, reusing Gatsby functionality can be done in a plugin too, but not for multiple needs

this evaluation is still ongoing, feel free to contribute ideas and suggestions

[github-actions]

Hiya!

This issue has gone quiet. Spooky quiet. 👻

We get a lot of issues, so we currently close issues after 30 days of inactivity. It’s been at least 20 days since the last update here.
If we missed this issue or if you want to keep it open, please reply here. You can also add the label "not stale" to keep this issue open!
As a friendly reminder: the best way to see this issue, or any other, fixed is to open a Pull Request. Check out gatsby.dev/contribute for more information about opening PRs, triaging issues, and contributing!

Thanks for being a part of the Gatsby community! 💪💜

[gillkyle]

Because the plugin tutorial content is covered in issue #16095 and that's the last recommendation of this evaluation, I'm going to close this in favor of that to narrow the scope of what needs to be finished.