From 0214ea558210d64ae75fccd482bbddf623d9ae14 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 23 Jan 2019 09:34:33 -0800
Subject: [PATCH] Update and Organize Contributors Guide per #12916 (#13352)

* Organize and reorder Contributors Guide per #12916

* Remove individual outreach pages, combined into single outreach.md

* Principles link, sections heading

* Fix link

* Fix link, typo

* Update docs/contributors/readme.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Remove meetups, there are far too many to list, since most meetups now all cover Gutenberg in some degree or other

* Update CONTRIBUTING with links to Documentation section

* Update CONTRIBUTING.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Update CONTRIBUTING.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Update CONTRIBUTING.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Update docs/contributors/outreach.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Update docs/contributors/outreach.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Update docs/contributors/document.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Update docs/contributors/document.md

Co-Authored-By: mkaz <marcus@mkaz.com>

* Add some newlines, take some away

* Paragraph for resources

* Update title in generator

* Update docs/contributors/develop.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 CONTRIBUTING.md                         |  24 ++---
 bin/generate-public-grammar.js          |   2 +-
 docs/contributors/copy-guide.md         |  30 +++---
 docs/contributors/design.md             |   2 +-
 docs/contributors/develop.md            |  11 ++
 docs/contributors/document.md           |  34 +++++++
 docs/contributors/grammar.md            |   2 +-
 docs/contributors/outreach.md           |  64 +++++++++---
 docs/contributors/outreach/articles.md  |  30 ------
 docs/contributors/outreach/meetups.md   |  17 ----
 docs/contributors/outreach/resources.md |  11 --
 docs/contributors/outreach/talks.md     |  17 ----
 docs/contributors/readme.md             |  17 +++-
 docs/grammar.md                         |   6 ++
 docs/manifest.json                      | 130 +++++++++++-------------
 docs/toc.json                           |  37 ++++---
 16 files changed, 215 insertions(+), 219 deletions(-)
 create mode 100644 docs/contributors/develop.md
 create mode 100644 docs/contributors/document.md
 delete mode 100644 docs/contributors/outreach/articles.md
 delete mode 100644 docs/contributors/outreach/meetups.md
 delete mode 100644 docs/contributors/outreach/resources.md
 delete mode 100644 docs/contributors/outreach/talks.md
 create mode 100644 docs/grammar.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 41fbdc022d8f6..576e78b27a3ee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,10 +4,12 @@ Thank you for thinking about contributing to WordPress' Gutenberg project! If yo
 
 As with all WordPress projects, we want to ensure a welcoming environment for everyone. With that in mind, all contributors are expected to follow our [Code of Conduct](/CODE_OF_CONDUCT.md).
 
-Before contributing, we encourage you to read our [Contributing Policy](/CONTRIBUTING.md) (you're here already!) and our [Handbook](https://wordpress.org/gutenberg/handbook/). If you have any questions on any of these, please open an issue so we can help clarify them.
+Before contributing, we encourage you to review the [Contributor Handbook](https://wordpress.org/gutenberg/handbook/contributors/). If you have any questions, please ask, either in Slack or open an issue in GitHub so we can help clarify.
 
 All WordPress projects are [licensed under the GPLv2+](/LICENSE.md), and all contributions to Gutenberg will be released under the GPLv2+ license. You maintain copyright over any contribution you make, and by submitting a pull request, you are agreeing to release that contribution under the GPLv2+ license.
 
+This document covers the technical details around setup, and submitting your contribution to the Gutenberg project.
+
 ## Getting Started
 
 Gutenberg is a Node.js-based project, built primarily in JavaScript.
@@ -114,7 +116,7 @@ Gutenberg contains both PHP and JavaScript code and encourages testing and code
 
 This repository uses [lerna] to manage Gutenberg modules and publish them as packages to [npm]. This enforces certain steps in the workflow which are described in details in [packages](/packages/README.md) documentation.
 
-Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. As a contributor you should add an entry to the aforementioned file each time you contribute adding production code as described in [Maintaining Changelogs](/packages/README.md#maintaining-changelogs) section. 
+Maintaining dozens of npm packages is difficult—it can be tough to keep track of changes. That's why we use `CHANGELOG.md` files for each package to simplify the release process. As a contributor you should add an entry to the aforementioned file each time you contribute adding production code as described in [Maintaining Changelogs](/packages/README.md#maintaining-changelogs) section.
 
 ## How Can Designers Contribute?
 
@@ -122,23 +124,9 @@ If you'd like to contribute to the design or front-end, feel free to contribute
 
 ## Contribute to the Documentation
 
-Documentation is automatically synced from master to the [Gutenberg Documentation Website](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
-
-To add a new documentation page, you'll have to create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder and add an item to the [toc.json](/docs/toc.json).
-
-### Using links
-
-It's very likely that at some point you will want to link to other documentation pages. It's worth emphasizing that all documents can be browsed in different contexts:
-- Gutenberg Handbook
-- GitHub website
-- npm website
-
-That's why it's recommended to use absolute links without the `https://github.com/WordPress/gutenberg` part for all files which match the following patterns:
-- `/docs/*.md`
-- `/packages/*/README.md`
-- `/packages/components/src/**/README.md`
+Please see the [Documentation section](/docs/contributors/document.md) of the Contributor Handbook.
 
-This way they will be properly handled in all three aforementioned contexts.
+Documentation is automatically synced from `master` to the [Gutenberg Handbook](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
 
 ### `@wordpress/component`
 
diff --git a/bin/generate-public-grammar.js b/bin/generate-public-grammar.js
index a049d1674f36d..c56ec4398a894 100755
--- a/bin/generate-public-grammar.js
+++ b/bin/generate-public-grammar.js
@@ -93,7 +93,7 @@ function flatten( expression ) {
 
 fs.writeFileSync(
 	path.join( __dirname, '..', 'docs', 'grammar.md' ), `
-# The Gutenberg block grammar
+# Block Grammar
 
 ${ flatten( grammar ) }
 ` );
diff --git a/docs/contributors/copy-guide.md b/docs/contributors/copy-guide.md
index 5e0066a689604..e5505e30f3acb 100644
--- a/docs/contributors/copy-guide.md
+++ b/docs/contributors/copy-guide.md
@@ -1,4 +1,4 @@
-# Gutencopy Guidelines
+# Copy Guidelines
 
 ## Longer Text
 Guidelines for writing multi-line/step instructions or narrative introductions/orientation to pages or features.
@@ -8,7 +8,7 @@ This will obviously vary quite a lot depending on the context, but here are some
 #### ONE: Contractions are your friends!
 They’re more conversational, and a simple way to make text sound friendlier and less formal. (And they save a bit of space as well: a win-win.)
 
-#### TWO: Cut phrases that inflate your word count without actually adding meaning. 
+#### TWO: Cut phrases that inflate your word count without actually adding meaning.
 This happens frequently in two specific instances. First, when writing in the passive voice:
 
 > This block can be used to display single images.
@@ -25,7 +25,7 @@ Does it or doesn’t it? We’re making this software: we’re allowed to be dec
 
 > The gallery block displays multiple images in an elegant layout.
 
-We also all do this a lot with the phrase “allows you to.” 
+We also all do this a lot with the phrase “allows you to.”
 
 > Preformatted text allows you to keep your tabs and line breaks.
 
@@ -33,9 +33,9 @@ Features don’t allow anyone to do anything; they’re just tools that do speci
 
 > Preformatted text preserves your tabs and line breaks.
 
-The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps”—they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up. 
+The more direct sentences are almost always clearer. Scan your copy for the words “can,” “be,” “might,” “allows you to,” and “helps”—they’re the most common culprits, and looking for those words specifically is a way to locate phrasing you can tighten up.
 
-#### THREE: Beware of “simple,” “easy,” and “just.” 
+#### THREE: Beware of “simple,” “easy,” and “just.”
 It is not for us to decide what is simple: it’s for the user to decide. If we say something is easy and the user doesn’t have an easy experience, it undermines their trust in us and what we’re building. Same goes for “just”—many of us know to avoid “simple,” but still use “just” all the time. “Just click here.” “Just enter your username.” It’s the same thing: it implies that something will be no big deal, but we can’t know what the user will find to be a big deal.
 
 It’s also safer and more helpful to be specific. “Easy” and “simple” are shorthand for explanations that we haven’t written; whenever you see them, take a minute to think about what they’re standing in for. Maybe “It’s easy to add a block by hitting ‘enter’” really means “You can add more content to the page without taking your hands off the keyboard.” Great! Say the specific thing instead of relying on “easy.”
@@ -43,7 +43,7 @@ It’s also safer and more helpful to be specific. “Easy” and “simple” a
 This isn’t to say that you should banish these words from your vocabulary. You might want to write a tooltip describing how the cover image block now requires less configuration, or an email about how we’re building a tool for quick creation of custom blocks, and you could legitimately say that the cover image block has been simplified or that we’re working to make custom block creation easier—there, the terms are descriptive and relative. But be on the lookout for ways you might be using (or overusing) them to make absolute claims that something is easy or simple, and use those as opportunities to be more specific and clear.
 
 #### FOUR: Look out for “we.”
-Any time text or instructions uses “we” a lot, it means the focus of the text is on the people behind the software and not the people using the software. Sometimes that’s what you actually want—but it’s usually not. The focus should typically be on the user, what they need, and how they benefit rather than “what we did” or “what we want.” 
+Any time text or instructions uses “we” a lot, it means the focus of the text is on the people behind the software and not the people using the software. Sometimes that’s what you actually want—but it’s usually not. The focus should typically be on the user, what they need, and how they benefit rather than “what we did” or “what we want.”
 
 We’re the only ones that care about what we did or want; the user just wants software that works. If you see a lot of “we”s, think about whether you should reframe what you’re writing to focus on the benefits to and successes of the user.
 
@@ -51,7 +51,7 @@ We’re the only ones that care about what we did or want; the user just wants s
 Guidelines for (duh) writing bulleted lists.
 
 #### ONE: Keep sentence structures parallel across all bullets.
-Parallel structure makes lists easier to read quickly—their predictability takes some cognitive load off the reader.	
+Parallel structure makes lists easier to read quickly—their predictability takes some cognitive load off the reader.
 
 GOOD:
 > What can you do with this block? Lots of things!
@@ -60,7 +60,7 @@ GOOD:
 > * Display multiple images.
 > * Create a bulleted list.
 
-Every bullet is a full sentence, and ends with a period. (If your list is a bunch of one- or two-word items, those can often just turn into a single regular sentence—easier to read, and space-saving.) Every line begins with a verb that tells the user what the block can do. The subject of the sentence is always the user. 
+Every bullet is a full sentence, and ends with a period. (If your list is a bunch of one- or two-word items, those can often just turn into a single regular sentence—easier to read, and space-saving.) Every line begins with a verb that tells the user what the block can do. The subject of the sentence is always the user.
 
 A user can absorb this list quickly because once they read the first item, they understand how to read the rest and know what information they’ll find.
 
@@ -101,7 +101,7 @@ If your list is more persuasive (e.g., trying to convince someone to use a featu
 >* Use it to highlight a link you love—sharing links is the currency of the internet.
 >* Create a gallery that displays multiple images, and show off your best photos.
 
-These aren’t hard-and-fast rules—you might choose the use the same verb in a persuasive list to be more focused and powerful, for example. But they’re good starting places for solid lists. 
+These aren’t hard-and-fast rules—you might choose the use the same verb in a persuasive list to be more focused and powerful, for example. But they’re good starting places for solid lists.
 
 #### THREE: When something's clearly a list, you don't have to tell us it's a list.
 
@@ -120,7 +120,7 @@ LESS GOOD:
 Find the balance between being as clear as possible and trusting a user. On one hand, we know that people don’t always read instructions; on the other, redundancy can make the user feel like we think they’re stupid.
 
 #### FOUR: Bold is sometimes your friend.
-Use it to focus readers on the key information in a bulleted list. This is especially useful when your bullets include some supplemental but ultimately secondary information. 
+Use it to focus readers on the key information in a bulleted list. This is especially useful when your bullets include some supplemental but ultimately secondary information.
 
 “Key information” is, well, key: bold draws the eye, so stick to the most vital piece of information in a given bullet:
 
@@ -136,7 +136,7 @@ On the flipside, bolding too many things creates visual confusion:
 > * Use it to highlight a **link** you love—sharing **links** is the currency of the internet.
 > * Create a **gallery** that displays **multiple images**, and show off your best **photos**.
 
-When lists are short and basic, don't bother—bolding just adds busy-ness. 
+When lists are short and basic, don't bother—bolding just adds busy-ness.
 
 > What can you do with this block? Lots of things!
 > * Add a **quote**.
@@ -148,7 +148,7 @@ The lack of words creates its own focus; you don't have to add any more.
 ## UI Descriptions
 Guidelines for writing one-line feature descriptions, or short descriptions to clarify options.
 
-#### ONE: Clarity above all! 
+#### ONE: Clarity above all!
 If the user doesn't understand what using a particular option will result in, it doesn't matter how clever your pun is. Wordplay and idioms are frequently unclear, and easily misunderstood. If you use them at all, they should be as supplemental information— never to explain the main idea—and they should be something you’re fairly certain will be understandable to a pretty wide range of people.
 
 #### TWO: Refer back to section one, and look out for those bulk-adding phrases.
@@ -187,7 +187,7 @@ And when something means everything, it actually means nothing. The more specifi
 #### FOUR: This is still writing. It should have personality and interest.
 Clarity above all, yes, and space is often limited here—but UI text can still be interesting to read.
 
-Single lines of description can still be complete sentences. 
+Single lines of description can still be complete sentences.
 
 > List. Numbered or bulleted.
 
@@ -195,7 +195,7 @@ vs.
 
 > Add a list, either numbered or bulleted.
 
-You can still use contractions. 
+You can still use contractions.
 
 > Add a list. We will provide formatting options.
 
@@ -203,7 +203,7 @@ vs.
 
 > Add a bulleted list—we’ll give you some formatting options.
 
-You can still use punctuation—em dashes, colons, semicolons—to control the flow of your words, link ideas, and create pauses. 
+You can still use punctuation—em dashes, colons, semicolons—to control the flow of your words, link ideas, and create pauses.
 
 > List. Numbered or bulleted.
 
diff --git a/docs/contributors/design.md b/docs/contributors/design.md
index 7b037fd3a4c94..bd68ba060718e 100644
--- a/docs/contributors/design.md
+++ b/docs/contributors/design.md
@@ -1,4 +1,4 @@
-# Gutenberg Design Principles & Vision
+# Design Principles & Vision
 
 This is a living document that outlines the design principles and patterns of the editor interface. Its aim is to explain the background of the design, inform future improvements, and help people design great blocks.
 
diff --git a/docs/contributors/develop.md b/docs/contributors/develop.md
new file mode 100644
index 0000000000000..97fa91aab0f78
--- /dev/null
+++ b/docs/contributors/develop.md
@@ -0,0 +1,11 @@
+# Developer Contributions
+
+Please see [CONTRIBUTING.md](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details on how to setup and make contributions to the Gutenberg repository.
+
+The following resources offer additional information for developers who wish to contribute to Gutenberg:
+
+* [Coding Guidelines](/docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
+* [Gutenberg Block Grammar](/docs/contributors/grammar.md)
+* [Testing Overview](/docs/contributors/testing-overview.md) for PHP and JavaScript development in Gutenberg.
+* [Scripts](/docs/contributors/scripts.md) a list of vendor and internal scripts available to plugin developers.
+* [Gutenberg Release Process](/docs/contributors/release.md) a checklist for the different type of releases for Gutenberg project.
diff --git a/docs/contributors/document.md b/docs/contributors/document.md
new file mode 100644
index 0000000000000..f51578d99e3c3
--- /dev/null
+++ b/docs/contributors/document.md
@@ -0,0 +1,34 @@
+# Documentation Contributions
+
+Documentation for Gutenberg is maintained in the `/docs/` directory in the same Gutenberg Github repository. The docs are published every 15 minutes to the [Gutenberg Handbook site](https://wordpress.org/gutenberg/handbook/).
+
+## New Document
+
+To add a new documentation page:
+
+1. Create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder
+2. Add item to the [toc.json](https://github.com/WordPress/gutenberg/blob/master/docs/toc.json) hierarchy
+3. Update manifest.json by running `npm run docs:build`
+4. Commit manifest.json with other files updated
+
+## Using Links
+
+It's very likely that at some point you will want to link to other documentation pages. It's worth emphasizing that all documents can be browsed in different contexts:
+
+- Gutenberg Handbook
+- GitHub website
+- npm website
+
+To create links that work in all contexts, you should use absolute path links without the `https://github.com/WordPress/gutenberg` prefix. You can reference files using the following patterns:
+
+- `/docs/*.md`
+- `/packages/*/README.md`
+- `/packages/components/src/**/README.md`
+
+This way they will be properly handled in all three aforementioned contexts.
+
+## Resources
+
+* [Copy Guidelines](/docs/contributors/copy-guide.md) for writing instructions, documentations, or other contributions to Gutenberg project.
+
+* [Tone and Voice Guide](https://make.wordpress.org/docs/handbook/documentation-team-handbook/tone-and-voice-guide/) from WordPress Documentation.
diff --git a/docs/contributors/grammar.md b/docs/contributors/grammar.md
index ac6015b9a2dc7..7d7e9bf73b8c0 100644
--- a/docs/contributors/grammar.md
+++ b/docs/contributors/grammar.md
@@ -1,5 +1,5 @@
 
-# The Gutenberg block grammar
+# Block Grammar
 
 <dl><dt></dt><dd><pre><header>Block_List</header>  = $(!Block .)* (Block $(!Block .)*)* $(.*)</pre></dd><dt></dt><dd><pre><header>Block</header>  = Block_Void
   / Block_Balanced</pre></dd><dt></dt><dd><pre><header>Block_Void</header>  = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __)? "/-->"</pre></dd><dt></dt><dd><pre><header>Block_Balanced</header>  = Block_Start (Block / $(!Block_End .))* Block_End</pre></dd><dt></dt><dd><pre><header>Block_Start</header>  = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __)? "-->"</pre></dd><dt></dt><dd><pre><header>Block_End</header>  = "&lt;!--" __ "/wp:" Block_Name __ "-->"</pre></dd><dt></dt><dd><pre><header>Block_Name</header>  = Namespaced_Block_Name
diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md
index 9df69e7ac58b6..208a1eaf707e1 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -1,8 +1,58 @@
 # Outreach
 
-This will include talks, meetups and anything the community is doing to discuss, learn about, and contribute to Gutenberg. This is not an exhaustive list, if we are missing your event just let us know.
+This includes articles, talks, demos and anything the community is doing to discuss, learn about, and contribute to Gutenberg. This is not an exhaustive list; if we are missing your event or article, just let us know.
+
+## Articles
+
+A short list of useful articles around defining, extending, and contributing to Gutenberg.
+
+### Overviews of Gutenberg
+
+- [Gutenberg, or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/), Matías Ventura Bausero (October 2017)
+- [We Called It Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/), Matt Mullenweg (August 2017)
+- [How Gutenberg is Changing WordPress Development](https://riad.blog/2017/10/06/how-gutenberg-is-changing-wordpress-development/), Riad Benguella (October 2017)
+- [How Gutenberg Will Shape the Future of WordPress](https://www.linkedin.com/pulse/gutenberg-morten-rand-hendriksen/), Morten Rand-Henrikson (August 2017)
+
+### Extending Gutenberg
+
+- [With Gutenberg, what happens to my Custom Fields?](https://riad.blog/2017/12/11/with-gutenberg-what-happens-to-my-custom-fields/), Riad Benguella (December 2017)
+- [One thousand and one ways to extend Gutenberg today](https://riad.blog/2017/10/16/one-thousand-and-one-way-to-extend-gutenberg-today/), Riad Benguella (October 2017)
+- [Gutenberg Plugin Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate/), Ahmad Awais (August 2017)
+
+### Community Contribution
+
+- [Gutenberg Block Library](https://editorblockswp.com/library), Danny Cooper (August 2018)
+- [A zero-configuration developer toolkit for building WordPress Gutenberg block plugins](https://ahmadawais.com/create-guten-block-toolkit/), Ahmad Awais (January 2018)
+- [Contributing to Gutenberg Without Code](https://wordimpress.com/a-pot-stirrer-amongst-chefs-contributing-to-gutenberg-without-code/), Kevin Hoffman (August 2017)
+- [Testing Flow in Gutenberg: Instructions for how to contribute to usability testing](https://make.wordpress.org/test/2017/11/22/testing-flow-in-gutenberg/), Anna Harrison (November 2017)
+
+### Article Compilations
+
+- [Curated Collection of Gutenberg Articles, Plugins, Blocks, Tutorials, etc](http://gutenberghub.com/), By Munir Kamal
+- [Articles about Gutenberg](https://github.com/WordPress/gutenberg/issues/1419) (Github Issue thread with links)
+- [Gutenberg articles on ManageWP.org](https://managewp.org/search?q=gutenberg)
+- [Gutenberg Times](https://gutenbergtimes.com/category/updates/)
+
+## Talks
+
+Talks given about Gutenberg, including slides and videos as they are available.
+
+### Slides
+- [The new core WordPress editor](http://kimb.me/talk-bigwp-london-new-core-wordpress-editor/) at BigWP London (18. May 2017)
+- [Gutenberg Notes](http://haiku2.com/2017/09/bend-wordpress-meetup-gutenberg-notes/) at Bend WordPress Meetup (5. September 2017)
+- [Gutenberg and the Future of Content in WordPress](https://www.slideshare.net/andrewmduthie/gutenberg-and-the-future-of-content-in-wordpress) (20. September 2017)
+- [Head first into Gutenberg](https://speakerdeck.com/prtksxna/head-first-into-gutenberg) at the [WordPress Goa Meet-up](https://www.meetup.com/WordPressGoa/events/245275573/) (1. December 2017)
+- [Gutenberg : vers une approche plus fine du contenu](https://imathi.eu/2018/02/16/gutenberg-vers-une-approche-plus-fine-du-contenu/) at [WP Paris](https://wpparis.fr/) (8. February 2018)
+
+### Videos
+- [All `Gutenberg` tagged Talks at WordPress.tv](https://wordpress.tv/tag/gutenberg/)
+- 2018-Jun - [Beyond Gutenberg](https://wordpress.tv/2018/07/09/matias-ventura-beyond-gutenberg/) by Matías Ventura
+- 2018-Jun - [Anatomy of a block: Gutenberg design patterns](https://wordpress.tv/2018/07/08/tammie-lister-anatomy-of-a-block-gutenberg-design-patterns/) by Tammie Lister
+- 2017-Dec - [State of the Word 2017](https://wordpress.tv/2017/12/04/matt-mullenweg-state-of-the-word-2017/) by Matt Mullenweg (Gutenberg demo by Matías Ventura at 35:00)
+- [Gutenberg is Coming (Don’t Be Afraid)](https://training.ithemes.com/webinar/gutenberg-is-coming-dont-be-afraid/) from iThemes Training
 
 ## Showcases or demonstrations:
+
 https://wpleeds.co.uk/events/plugins-gutenberg-wordpress-leeds-july-2017/
 
 http://kimb.me/talk-bigwp-london-new-core-wordpress-editor
@@ -13,15 +63,3 @@ https://www.meetup.com/WordPress-Melbourne/events/241543639
 
 https://wpmeetups.de/termin/29-wp-meetup-stuttgart-gutenberg-editor-rueckblick-wordcamp-europe/
 
-## Testing events: 
-https://www.meetup.com/Turku-WordPress-Meetup/events/241195076/
-
-https://www.meetup.com/Vancouver-WordPress-Meetup-Group/events/241575161/
-
-## Calls for testing: 
-https://make.wordpress.org/test/2017/06/27/call-for-testing-gutenberg/
-
-http://www.wpswfl.org/new-wordpress-editor-gutenberg-early-beta-needs-testers/
-
-https://gutenberg.eastbaywp.com
-
diff --git a/docs/contributors/outreach/articles.md b/docs/contributors/outreach/articles.md
deleted file mode 100644
index fe4bce7e328a8..0000000000000
--- a/docs/contributors/outreach/articles.md
+++ /dev/null
@@ -1,30 +0,0 @@
-# Articles
-
-This includes useful articles for those wanting to run a meetup or promote Gutenberg.
-
-## Overviews of Gutenberg
-
-- [Gutenberg, or the Ship of Theseus](https://matiasventura.com/post/gutenberg-or-the-ship-of-theseus/), Matías Ventura Bausero (October 2017)
-- [We Called It Gutenberg for a Reason](https://ma.tt/2017/08/we-called-it-gutenberg-for-a-reason/), Matt Mullenweg (August 2017)
-- [How Gutenberg is Changing WordPress Development](https://riad.blog/2017/10/06/how-gutenberg-is-changing-wordpress-development/), Riad Benguella (October 2017)
-- [How Gutenberg Will Shape the Future of WordPress](https://www.linkedin.com/pulse/gutenberg-morten-rand-hendriksen/), Morten Rand-Henrikson (August 2017)
-
-## Extending Gutenberg
-
-- [With Gutenberg, what happens to my Custom Fields?](https://riad.blog/2017/12/11/with-gutenberg-what-happens-to-my-custom-fields/), Riad Benguella (December 2017)
-- [One thousand and one ways to extend Gutenberg today](https://riad.blog/2017/10/16/one-thousand-and-one-way-to-extend-gutenberg-today/), Riad Benguella (October 2017)
-- [Gutenberg Plugin Boilerplate](https://github.com/ahmadawais/Gutenberg-Boilerplate/), Ahmad Awais (August 2017)
-
-## Community Contribution
-
-- [Gutenberg Block Library](https://editorblockswp.com/library), Danny Cooper (August 2018)
-- [A zero-configuration developer toolkit for building WordPress Gutenberg block plugins](https://ahmadawais.com/create-guten-block-toolkit/), Ahmad Awais (January 2018)
-- [Contributing to Gutenberg Without Code](https://wordimpress.com/a-pot-stirrer-amongst-chefs-contributing-to-gutenberg-without-code/), Kevin Hoffman (August 2017)
-- [Testing Flow in Gutenberg: Instructions for how to contribute to usability testing](https://make.wordpress.org/test/2017/11/22/testing-flow-in-gutenberg/), Anna Harrison (November 2017)
-
-## Article Compilations
-
-- [Curated Collection of Gutenberg Articles, Plugins, Blocks, Tutorials, etc](http://gutenberghub.com/), By Munir Kamal
-- [Articles about Gutenberg](https://github.com/WordPress/gutenberg/issues/1419) (Github Issue thread with links)
-- [Gutenberg articles on ManageWP.org](https://managewp.org/search?q=gutenberg)
-- [Gutenberg Times](https://gutenbergtimes.com/category/updates/)
diff --git a/docs/contributors/outreach/meetups.md b/docs/contributors/outreach/meetups.md
deleted file mode 100644
index 58cd8bbb72c99..0000000000000
--- a/docs/contributors/outreach/meetups.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Meetups
-
-A list of meetups about Gutenberg so far:
-
-- [Gutenberg and the Future of WordPress](https://www.meetup.com/Vancouver-WordPress-Meetup-Group/events/241575161/), Vancouver, Canada
-- [Page builders and the upcoming Gutenberg Editor](https://www.meetup.com/Turku-WordPress-Meetup/events/241195076/), Turku, Finland
-- [Discussion about Gutenberg](https://www.facebook.com/events/278785795934302/), Andria, Italy
-- [Plugins and Gutenberg](https://wpleeds.co.uk/events/plugins-gutenberg-wordpress-leeds-july-2017/), Leeds, UK
-- [Gutenberg Introduction & Demo](https://www.meetup.com/WordPress-Melbourne/events/241543639/), Melbourne, Australia
-- [Gutenberg Editor & Review](https://wpmeetups.de/termin/29-wp-meetup-stuttgart-gutenberg-editor-rueckblick-wordcamp-europe/), WordCamp Europe
-- [Diving into Gutenberg by Tammie Lister](https://www.meetup.com/Big-Media-Enterprise-WordPress-London-Meetup/events/243302081/), London, UK
-- [What's New In WordPress 4.9 and Gutenberg 1.5](https://www.meetup.com/Tuscaloosa-WordPress-Meetup/events/244584939/), Tuscaloosa, Alabama, USA
-- [WordPress & JavaScript: Let's talk Gutenberg!](https://www.meetup.com/WordPress-Lahore/events/246446478/), Lahore, PK
-- [The state of Gutenberg](https://www.meetup.com/WP-Porto/events/245585131/), Porto, Portugal
-- [Discuss and learn about the new WordPress Editor : Gutenberg](https://www.meetup.com/Pune-WordPress-Knowledge-Exchange/events/248496830/), Pune, India
-- [An Introduction to Gutenberg](https://www.meetup.com/Okanagan-WordPress-Meetup/events/249167218/), Vernon, BC, Canada
-- [WordPress 5.0 - Gutenberg is upon us](https://www.meetup.com/WordPress-Perth/events/249490075/), Perth, Australia
diff --git a/docs/contributors/outreach/resources.md b/docs/contributors/outreach/resources.md
deleted file mode 100644
index 3c5dd598f6085..0000000000000
--- a/docs/contributors/outreach/resources.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Resources
-
-All resources here can be used by anyone. Feel free to use the decks to make your own talks or to use the gifs in your blog posts and other resources.
-
-## Slidedecks to use
-
-- v1: https://cloudup.com/cqEJppQ8m-5 : August 2017
-
-## Gif collection to use
-
-- https://cloudup.com/c9OKU3OJD9r
diff --git a/docs/contributors/outreach/talks.md b/docs/contributors/outreach/talks.md
deleted file mode 100644
index a21f9c468c481..0000000000000
--- a/docs/contributors/outreach/talks.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Talks
-
-Talks given about Gutenberg, including slides and videos as they are available.
-
-## Slides
-- [The new core WordPress editor](http://kimb.me/talk-bigwp-london-new-core-wordpress-editor/) at BigWP London (18. May 2017)
-- [Gutenberg Notes](http://haiku2.com/2017/09/bend-wordpress-meetup-gutenberg-notes/) at Bend WordPress Meetup (5. September 2017)
-- [Gutenberg and the Future of Content in WordPress](https://www.slideshare.net/andrewmduthie/gutenberg-and-the-future-of-content-in-wordpress) (20. September 2017)
-- [Head first into Gutenberg](https://speakerdeck.com/prtksxna/head-first-into-gutenberg) at the [WordPress Goa Meet-up](https://www.meetup.com/WordPressGoa/events/245275573/) (1. December 2017)
-- [Gutenberg : vers une approche plus fine du contenu](https://imathi.eu/2018/02/16/gutenberg-vers-une-approche-plus-fine-du-contenu/) at [WP Paris](https://wpparis.fr/) (8. February 2018)
-
-## Videos
-- [All `Gutenberg` tagged Talks at WordPress.tv](https://wordpress.tv/tag/gutenberg/)
-- 2018-Jun - [Beyond Gutenberg](https://wordpress.tv/2018/07/09/matias-ventura-beyond-gutenberg/) by Matías Ventura
-- 2018-Jun - [Anatomy of a block: Gutenberg design patterns](https://wordpress.tv/2018/07/08/tammie-lister-anatomy-of-a-block-gutenberg-design-patterns/) by Tammie Lister
-- 2017-Dec - [State of the Word 2017](https://wordpress.tv/2017/12/04/matt-mullenweg-state-of-the-word-2017/) by Matt Mullenweg (Gutenberg demo by Matías Ventura at 35:00)
-- [Gutenberg is Coming (Don’t Be Afraid)](https://training.ithemes.com/webinar/gutenberg-is-coming-dont-be-afraid/) from iThemes Training
diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
index 1feaadfcbf5b9..e3979c229e25c 100644
--- a/docs/contributors/readme.md
+++ b/docs/contributors/readme.md
@@ -2,10 +2,17 @@
 
 Welcome to the Gutenberg Project Contributors Guide.
 
-The following guidelines are in place to create consistency across the project and the numerous contributors. See also the [Contributing Documentation](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details around setup, and submitting your contributions.
+The following guidelines are in place to create consistency across the project and the numerous contributors. See the [Contributing Documentation](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for technical details around setup, and submitting your contributions.
 
-* [Coding Guidelines](../../docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
-* [Copy Guidelines](../../docs/contributors/copy-guide.md)
-* [Design Principles & Vision](../../docs/contributors/design.md)
+## Philosophy
+
+* [Architecturial and UX Principles of Gutenberg](/docs/contributors/principles.md)
+
+## Sections
+
+The contributors guide has the following different sections by contribution type:
+
+* [Design Contributions](/docs/contributors/design.md)
+* [Developer Contributions](/docs/contributors/develop.md)
+* [Documentation Contributions](/docs/contributors/document.md)
 
-Please see the table of contents on the left side of the Gutenberg Handbook for the full list of contributor resources.
diff --git a/docs/grammar.md b/docs/grammar.md
new file mode 100644
index 0000000000000..1bbe77dc5ecf0
--- /dev/null
+++ b/docs/grammar.md
@@ -0,0 +1,6 @@
+
+# Block Grammar
+
+<dl><dt></dt><dd><pre><header>Block_List</header>  = $(!Block .)* (Block $(!Block .)*)* $(.*)</pre></dd><dt></dt><dd><pre><header>Block</header>  = Block_Void
+  / Block_Balanced</pre></dd><dt></dt><dd><pre><header>Block_Void</header>  = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __)? "/-->"</pre></dd><dt></dt><dd><pre><header>Block_Balanced</header>  = Block_Start (Block / $(!Block !Block_End .)+)* Block_End</pre></dd><dt></dt><dd><pre><header>Block_Start</header>  = "&lt;!--" __ "wp:" Block_Name __ (Block_Attributes __)? "-->"</pre></dd><dt></dt><dd><pre><header>Block_End</header>  = "&lt;!--" __ "/wp:" Block_Name __ "-->"</pre></dd><dt></dt><dd><pre><header>Block_Name</header>  = Namespaced_Block_Name
+  / Core_Block_Name</pre></dd><dt></dt><dd><pre><header>Namespaced_Block_Name</header>  = $(Block_Name_Part "/" Block_Name_Part)</pre></dd><dt></dt><dd><pre><header>Core_Block_Name</header>  = $(Block_Name_Part)</pre></dd><dt></dt><dd><pre><header>Block_Name_Part</header>  = $([a-z] [a-z0-9_-]*)</pre></dd><dt>JSON-encoded attributes embedded in a block's opening comment</dt><dd><pre><header>Block_Attributes</header>  = $("{" (!("}" __ "" "/"? "-->") .)* "}")</pre></dd><dt></dt><dd><pre><header>__</header>  = [ \t\r\n]+</pre></dd></dl>
diff --git a/docs/manifest.json b/docs/manifest.json
index dfa85b7d12f34..e7d2a88e11cc5 100644
--- a/docs/manifest.json
+++ b/docs/manifest.json
@@ -365,18 +365,6 @@
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/designers/design-resources.md",
 		"parent": "designers"
 	},
-	{
-		"title": "Glossary",
-		"slug": "glossary",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/glossary.md",
-		"parent": "designers-developers"
-	},
-	{
-		"title": "Frequently Asked Questions",
-		"slug": "faq",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/faq.md",
-		"parent": "designers-developers"
-	},
 	{
 		"title": "Contributors Guide",
 		"slug": "contributors",
@@ -384,105 +372,105 @@
 		"parent": null
 	},
 	{
-		"title": "Coding Guidelines",
-		"slug": "coding-guidelines",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/coding-guidelines.md",
-		"parent": "contributors"
-	},
-	{
-		"title": "Gutencopy Guidelines",
-		"slug": "copy-guide",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/copy-guide.md",
+		"title": "Principles",
+		"slug": "principles",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/principles.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Gutenberg Design Principles & Vision",
+		"title": "Design Principles & Vision",
 		"slug": "design",
 		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/design.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "The Gutenberg block grammar",
-		"slug": "grammar",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/grammar.md",
-		"parent": "contributors"
+		"title": "Blocks are the Interface",
+		"slug": "the-block",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/principles/the-block.md",
+		"parent": "design"
 	},
 	{
-		"title": "History",
-		"slug": "history",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/history.md",
-		"parent": "contributors"
+		"title": "Reference",
+		"slug": "reference",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/reference.md",
+		"parent": "design"
 	},
 	{
-		"title": "Outreach",
-		"slug": "outreach",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/outreach.md",
+		"title": "Developer Contributions",
+		"slug": "develop",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/develop.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Articles",
-		"slug": "articles",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/outreach/articles.md",
-		"parent": "outreach"
+		"title": "Coding Guidelines",
+		"slug": "coding-guidelines",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/coding-guidelines.md",
+		"parent": "develop"
 	},
 	{
-		"title": "Meetups",
-		"slug": "meetups",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/outreach/meetups.md",
-		"parent": "outreach"
+		"title": "Block Grammar",
+		"slug": "grammar",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/grammar.md",
+		"parent": "develop"
 	},
 	{
-		"title": "Resources",
-		"slug": "resources",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/outreach/resources.md",
-		"parent": "outreach"
+		"title": "Testing Overview",
+		"slug": "testing-overview",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/testing-overview.md",
+		"parent": "develop"
 	},
 	{
-		"title": "Talks",
-		"slug": "talks",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/outreach/talks.md",
-		"parent": "outreach"
+		"title": "Scripts",
+		"slug": "scripts",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/scripts.md",
+		"parent": "develop"
 	},
 	{
-		"title": "Principles",
-		"slug": "principles",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/principles.md",
+		"title": "Gutenberg Release Process",
+		"slug": "release",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/release.md",
+		"parent": "develop"
+	},
+	{
+		"title": "Documentation Contributions",
+		"slug": "document",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/document.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Blocks are the Interface",
-		"slug": "the-block",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/principles/the-block.md",
-		"parent": "principles"
+		"title": "Copy Guidelines",
+		"slug": "copy-guide",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/copy-guide.md",
+		"parent": "document"
 	},
 	{
-		"title": "Reference",
-		"slug": "reference",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/reference.md",
+		"title": "History",
+		"slug": "history",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/history.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Gutenberg Release Process",
-		"slug": "release",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/release.md",
+		"title": "Glossary",
+		"slug": "glossary",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/glossary.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Repository Management",
-		"slug": "repository-management",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/repository-management.md",
+		"title": "Frequently Asked Questions",
+		"slug": "faq",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/designers-developers/faq.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Scripts",
-		"slug": "scripts",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/scripts.md",
+		"title": "Repository Management",
+		"slug": "repository-management",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/repository-management.md",
 		"parent": "contributors"
 	},
 	{
-		"title": "Testing Overview",
-		"slug": "testing-overview",
-		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/testing-overview.md",
+		"title": "Outreach",
+		"slug": "outreach",
+		"markdown_source": "https://raw.githubusercontent.com/WordPress/gutenberg/master/docs/contributors/outreach.md",
 		"parent": "contributors"
 	},
 	{
diff --git a/docs/toc.json b/docs/toc.json
index ceb639a213cf9..cdb3fa096507b 100644
--- a/docs/toc.json
+++ b/docs/toc.json
@@ -71,29 +71,28 @@
 			{"docs/designers-developers/designers/block-design.md": []},
 			{"docs/designers-developers/designers/design-patterns.md": []},
 			{"docs/designers-developers/designers/design-resources.md": []}
-		]},
-		{"docs/designers-developers/glossary.md": []},
-		{"docs/designers-developers/faq.md": []}
+		]}
 	]},
 	{"docs/contributors/readme.md": [
-		{"docs/contributors/coding-guidelines.md": []},
-		{"docs/contributors/copy-guide.md": []},
-		{"docs/contributors/design.md": []},
-		{"docs/contributors/grammar.md": []},
-		{"docs/contributors/history.md": []},
-		{"docs/contributors/outreach.md": [
-			{"docs/contributors/outreach/articles.md": []},
-			{"docs/contributors/outreach/meetups.md": []},
-			{"docs/contributors/outreach/resources.md": []},
-			{"docs/contributors/outreach/talks.md": []}
+		{"docs/contributors/principles.md": []},
+		{"docs/contributors/design.md": [
+			{"docs/contributors/principles/the-block.md": []},
+			{"docs/contributors/reference.md": []}
 		]},
-		{"docs/contributors/principles.md": [
-			{"docs/contributors/principles/the-block.md": []}
+		{"docs/contributors/develop.md": [
+			{"docs/contributors/coding-guidelines.md": []},
+			{"docs/contributors/grammar.md": []},
+			{"docs/contributors/testing-overview.md": []},
+			{"docs/contributors/scripts.md": []},
+			{"docs/contributors/release.md": []}
 		]},
-		{"docs/contributors/reference.md": []},
-		{"docs/contributors/release.md": []},
+		{"docs/contributors/document.md": [
+			{"docs/contributors/copy-guide.md": []}
+		]},
+		{"docs/contributors/history.md": []},
+		{"docs/designers-developers/glossary.md": []},
+		{"docs/designers-developers/faq.md": []},
 		{"docs/contributors/repository-management.md": []},
-		{"docs/contributors/scripts.md": []},
-		{"docs/contributors/testing-overview.md": []}
+		{"docs/contributors/outreach.md": []}
 	]}
 ]