diff --git a/docs/docs/plugin-authoring.md b/docs/docs/plugin-authoring.md
index 09d9d92955e5a..62bb7c6f65015 100644
--- a/docs/docs/plugin-authoring.md
+++ b/docs/docs/plugin-authoring.md
@@ -1,15 +1,14 @@
 ---
-title: Plugin Authoring
+title: Plugin authoring
 ---
 
-One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to extend and modify just about everything Gatsby does.
+You may be looking to build a plugin that doesn't exist yet, or you may just be curious to know more about the anatomy of a Gatsby plugin. We'll review:
 
-Of the many possibilities, plugins can:
-
-- add external data or content (e.g. your CMS, static files, a REST API) to your Gatsby GraphQL data
-- transform data from other formats (e.g. YAML, CSV) to JSON objects
-- add third-party services (e.g. Google Analytics, Instagram) to your site
-- anything you can dream up!
+1. the core concepts of what a Gatsby plugin is
+2. naming conventions for the plugin title
+3. expected files in a plugin package
+4. defining a local (unpublished) plugin for your own use case
+5. what a plugin is _not_
 
 ## Core Concepts
 
diff --git a/docs/docs/plugins.md b/docs/docs/plugins.md
index 67bf727ef26a3..a43c1ae644720 100644
--- a/docs/docs/plugins.md
+++ b/docs/docs/plugins.md
@@ -2,34 +2,42 @@
 title: Plugins
 ---
 
-Plugins are Node.js packages that implement Gatsby APIs. They enable you to
-easily solve common website build problems e.g. setup Sass, add markdown
-support, process images, etc.
+One of the best ways to add functionality to Gatsby is through our plugin system. Gatsby is designed to be extensible, which means plugins are able to extend and modify just about everything Gatsby does.
 
-For larger / complex sites, they let you modularize your site customizations
-into site-specific plugins.
+Of the many possibilities, plugins can:
 
-Gatsby has a large and growing set of plugins. To search/browse official and
-community plugins and their documentation, visit the [Plugin Library](/plugins/).
+- add external data or content (e.g. your CMS, static files, a REST API) to your Gatsby GraphQL data
+- transform data from other formats (e.g. Markdown, YAML, CSV) to JSON objects
+- add third-party services (e.g. Google Analytics, Instagram) to your site
+- anything you can dream up!
 
-For documentation on the different types of plugins and the functionality provided by each, see the [Plugin Authoring page](/docs/plugin-authoring/).
+Gatsby plugins are Node.js packages that implement Gatsby APIs. For larger, more complex sites, plugins let you modularize your site customizations into site-specific plugins.
 
-For a walkthrough of how to build and publish your own plugin, see the [Source Plugin Tutorial](/docs/source-plugin-tutorial/).
+## Search published plugins
 
-## How to use Gatsby plugins?
+Gatsby has a large and growing ecosystem of official and community plugins. To browse plugins and their documentation, visit the [Gatsby Plugin Library](/plugins/).
 
-Gatsby plugins are Node.js packages, so you can install them like other packages in
-node using NPM.
+## Learn more about plugins
 
-For example, `gatsby-transformer-json` is a package which adds support for JSON
-files to the Gatsby data layer.
+For documentation with further detail on what comprises a Gatsby plugin (file structure, etc), see the [plugin authoring page](/docs/plugin-authoring/).
+
+## Build and publish a plugin
+
+For a walkthrough of how to build and publish your own plugin, see the [source plugin tutorial](/docs/source-plugin-tutorial/).
+
+## Use a plugin in your site
+
+Gatsby plugins are Node.js packages, so you can install them like other packages in node using NPM.
+
+For example, `gatsby-transformer-json` is a package which adds support for JSON files to the Gatsby data layer.
 
 To install it, in the root of your site you run:
 
-`npm install --save gatsby-transformer-json`
+```bash
+npm install --save gatsby-transformer-json
+```
 
-Then in your site's `gatsby-config.js` you add `gatsby-transformer-json`
-to the plugins array like:
+Then in your site's `gatsby-config.js` you add `gatsby-transformer-json` to the plugins array like:
 
 ```javascript
 module.exports = {
@@ -37,7 +45,7 @@ module.exports = {
 }
 ```
 
-Plugins can take options. Examples:
+Plugins can take options. For example:
 
 ```javascript
 module.exports = {