docs: flowchart and tables for differences between plugins, themes, and starters

docs/docs/plugins-themes-and-starters.md

@@ -37,6 +37,12 @@ Gatsby offers [official starters](/docs/starters/#official-starters) for a defau
 - [Creating a starter](/docs/creating-a-starter/)
 - [Converting a starter to a theme](/docs/themes/converting-a-starter/)
 
+## Conventions for usage
+
+Themes are a type of plugin, making both themes and plugins capable of the same functionality. The difference between them is the _intent for their usage_. Themes are intended to own a piece of the site (like an about us page), whereas a plugin is intended to modularize Gatsby APIs into smaller pieces. Themes tend to cover a broader scope of responsibility, packaging up multiple behaviors, where plugins are meant for a narrower use.
+
+Starters are generally used as the starting point that plugins and themes are then installed into.
+
 ## Comparing differences
 
 Once you have a conceptual understanding of what a plugin, theme, and starter is, you may ask yourself what each is suited for in relation to each other.
@@ -51,9 +57,9 @@ The following tables put plugins, themes, and starters side-by-side, showing wha
 | ◐    | Somewhat capable (not as recommended of a practice or less supported) |
 | ○    | Not capable                                                           |
 
-### Differences in maintainability
+### Differences and considerations in maintenance
 
-When it comes to maintaining a Gatsby site, plugins and themes offer a distinct advantage to starters by being distributed as packages, making pulling in upstream changes in multiple Gatsby sites as easy as a new install.
+When it comes to maintaining a Gatsby site, plugins and themes offer a distinct advantage to starters by being distributed as packages. This means making changes in multiple Gatsby sites is as easy as a new install of an updated package upstream. It's difficult to sync changes across multiple sites derived from the same starter.
 
 | Maintenance        | Plugin | Theme | Starter |
 | ------------------ | ------ | ----- | ------- |
@@ -62,15 +68,15 @@ When it comes to maintaining a Gatsby site, plugins and themes offer a distinct
 
 #### Versioning
 
-Starters can still be versioned inside a repository so that you can track issues or bugs associated with specific developments in the starter but it's more difficult to make updates with new changes.
+Starters can still be versioned inside of a repository so that you can track issues or bugs associated with specific developments, but they aren't formally released in publishes marked by versions like a plugin or theme is.
 
 #### Installing as a package
 
-Because starters are "ejected" each time they are used, it's difficult to sync changes across multiple sites derived from the same starter. This problem was one of the motivating factors in developing the newer concept of themes for Gatsby. You can read more about why themes were developed in the [What are Gatsby Themes guide](/docs/themes/what-are-gatsby-themes/#gatsby-starters).
+Starters can't be installed into existing sites, this problem was one of the motivating factors in developing the newer concept of themes. You can read more about the rationale for themes in the [What are Gatsby Themes guide](/docs/themes/what-are-gatsby-themes/#gatsby-starters).
 
-### Differences in configurability
+### Differences and considerations in configuration
 
-Plugins and themes can expose options to make them configurable for users. There are different options for configuration like passing in options and shadowing files that make plugins and themes more powerful—but also more complicated—than starters.
+Plugins and themes can expose options to make them configurable for users. There are different possibilities for configuration like passing in options and shadowing files that make plugins and themes more powerful—but also more complicated—than starters. Because themes are also plugins, shadowing is possible in plugins as well. It may make sense for a plugin to take advantage of the shadowing API, but it is less common.
 
 | Configuration         | Plugin | Theme | Starter |
 | --------------------- | ------ | ----- | ------- |
@@ -85,23 +91,23 @@ Plugins and themes both allow options to be passed in when installed in the plug
 
 #### Shadowing
 
-The options exposed by a plugin or theme are up to the author. For example, a plugin or theme can allow a specific path to be provided in the `gatsby-config` so the plugin knows where to build pages from. In this case the user wouldn't be able adjust _how_ those pages are built, only from what path. As an escape hatch to change small pieces of an installed theme, [shadowing](/docs/themes/shadowing/) was introduced. Theme shadowing allows users to replace a file with their own version of it. Because themes are also plugins, shadowing is possible in plugins as well.
+As an escape hatch to change small pieces of an installed theme, [shadowing](/docs/themes/shadowing/) was introduced. For example, a plugin or theme could allow a specific path to be provided in the `gatsby-config` so the plugin knows where to build pages from, but the user wouldn't be able adjust _how_ those pages are built, only from what path. Theme shadowing allows users to replace a file with their own version of it, allowing them to rewrite that logic to use the path in a different way.
 
 An example of a plugin that uses shadowing is [`gatsby-plugin-theme-ui`](/packages/gatsby-plugin-theme-ui/?=theme-ui#customizing-the-theme) which allows you to shadow a theme file to use your own theme.
 
 Starters aren't capable of shadowing (and they don't need to be), because a user of a starter can adjust any file by editing it directly.
 
 #### Uses multiple plugins
 
-Starters can be configured with multiple plugins so someone can get up and running without worrying about configuring too many loose ends. Themes are capable of the same by making a `gatsby-config` that a Gatsby site will run along with its own config. Plugins are also capable of this (because themes are a plugin), but it is recommended that _plugins be limited to their specific functionality_.
+Themes are intended to abstract several plugins into one, by making a `gatsby-config` that a Gatsby site will run along with its own config. Starters can also be configured with multiple plugins so someone can get up and running without worrying about configuring too many loose ends.
 
 #### Custom components
 
 Custom components are most traditionally distributed as packages in the React ecosystem. Components don't need to hook into the Gatsby build system, so if shipped with a plugin they don't need to be included in a `gatsby-config`'s plugin array. This is the case with `gatsby-image` which is a React component. It doesn't need to be included in the plugins array because it is merely a component.
 
-Some plugins and themes ship with components you can use in a Gatsby site. An example is the [`<OutboundLink />` component from `gatsby-plugin-google-analytics`](/packages/gatsby-plugin-google-analytics/?=#outboundlink-component). Other plugins, like [`gatsby-plugin-react-helmet`](/packages/gatsby-plugin-react-helmet), require you to install components from other dependent libraries.
+Some plugins ship with components you can use in a Gatsby site. An example is the [`<OutboundLink />` component from `gatsby-plugin-google-analytics`](/packages/gatsby-plugin-google-analytics/?=#outboundlink-component). Other plugins, like [`gatsby-plugin-react-helmet`](/packages/gatsby-plugin-react-helmet), require you to install components from other dependent libraries.
 
-Because themes are meant to own a section of a site—like a page or part of a page—they are more suited to ship with components that could then be shadowed for customization.
+Themes by convention are more suited to ship with components that could then be shadowed for customization.
 
 Starters will include components to render data, but they are tied to the starter.