From 8bd929556ff0e17950e4a8547d74533cb93312dc Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 16 Jan 2019 15:56:19 -0800
Subject: [PATCH 01/19] Organize and reorder Contributors Guide per #12916

---
 CONTRIBUTING.md                 |   8 +-
 docs/contributors/copy-guide.md |  30 ++++----
 docs/contributors/design.md     |   2 +-
 docs/contributors/develop.md    |   9 +++
 docs/contributors/document.md   |   9 +++
 docs/contributors/grammar.md    |   2 +-
 docs/contributors/outreach.md   |  80 +++++++++++++++++---
 docs/contributors/readme.md     |  13 ++--
 docs/manifest.json              | 130 +++++++++++++++-----------------
 docs/toc.json                   |  37 +++++----
 10 files changed, 195 insertions(+), 125 deletions(-)
 create mode 100644 docs/contributors/develop.md
 create mode 100644 docs/contributors/document.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 41fbdc022d8f6..46a627a35b2da 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 [Contributors 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?
 
@@ -124,7 +126,7 @@ If you'd like to contribute to the design or front-end, feel free to contribute
 
 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).
+To add a new documentation page, you create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder and add an item to the [toc.json](https://github.com/WordPress/gutenberg/blob/master/docs/toc.json) and generate using `npm run docs:build`.
 
 ### Using links
 
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..5233012106405
--- /dev/null
+++ b/docs/contributors/develop.md
@@ -0,0 +1,9 @@
+# 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.
+
+* [Coding Guidelines](/docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
+* [Gutenberg Block Grammer](/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 interval script 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..1f2abfb0ca881
--- /dev/null
+++ b/docs/contributors/document.md
@@ -0,0 +1,9 @@
+# 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/).
+
+## 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..873c0af4777f6 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -1,8 +1,62 @@
 # 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 just let us know.
+
+
+
+## Articles
+
+A short list of useful articles around defining, extending, and contributing to Gutenberg project.
+
+### 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 +67,21 @@ 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/
+## Meetups
 
-https://gutenberg.eastbaywp.com
+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/readme.md b/docs/contributors/readme.md
index 1feaadfcbf5b9..319f274af2189 100644
--- a/docs/contributors/readme.md
+++ b/docs/contributors/readme.md
@@ -2,10 +2,13 @@
 
 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
+
+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/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": []}
 	]}
 ]

From 3d583cd4e3fbcb66f73b720e1ef483e919c569b2 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 16 Jan 2019 16:04:00 -0800
Subject: [PATCH 02/19] Remove individual outreach pages, combined into single
 outreach.md

---
 docs/contributors/outreach/articles.md  | 30 -------------------------
 docs/contributors/outreach/meetups.md   | 17 --------------
 docs/contributors/outreach/resources.md | 11 ---------
 docs/contributors/outreach/talks.md     | 17 --------------
 4 files changed, 75 deletions(-)
 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

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

From 6e2262b7ff736c494fde00047d75f7806c0adbbf Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 16 Jan 2019 16:06:01 -0800
Subject: [PATCH 03/19] Principles link, sections heading

---
 docs/contributors/readme.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
index 319f274af2189..6def9d97cbc32 100644
--- a/docs/contributors/readme.md
+++ b/docs/contributors/readme.md
@@ -6,6 +6,10 @@ The following guidelines are in place to create consistency across the project a
 
 ## Philosophy
 
+* [Architecturial and UX Principles of Gutenberg](/docs/contributors/principles/)
+
+## Sections
+
 The contributors guide has the following different sections by contribution type:
 
 * [Design Contributions](/docs/contributors/design.md)

From 1547a0baf346c0de2e09eb30caca2e1ee2a31389 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 16 Jan 2019 16:06:48 -0800
Subject: [PATCH 04/19] Fix link

---
 docs/contributors/readme.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
index 6def9d97cbc32..0c6d533779dba 100644
--- a/docs/contributors/readme.md
+++ b/docs/contributors/readme.md
@@ -6,7 +6,7 @@ The following guidelines are in place to create consistency across the project a
 
 ## Philosophy
 
-* [Architecturial and UX Principles of Gutenberg](/docs/contributors/principles/)
+* [Architecturial and UX Principles of Gutenberg](/docs/contributors/principles.md)
 
 ## Sections
 

From 1ce66df7d9e9241781f0065d18a28369473de4dc Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 16 Jan 2019 16:08:18 -0800
Subject: [PATCH 05/19] Fix link, typo

---
 docs/contributors/develop.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/contributors/develop.md b/docs/contributors/develop.md
index 5233012106405..93c4cc1b02888 100644
--- a/docs/contributors/develop.md
+++ b/docs/contributors/develop.md
@@ -1,9 +1,9 @@
 # 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.
+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.
 
 * [Coding Guidelines](/docs/contributors/coding-guidelines.md) outline additional patterns and conventions used in the Gutenberg project.
 * [Gutenberg Block Grammer](/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 interval script available to plugin developers.
+* [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.

From e0ef76a18a5691f9dabb5e991e7f2a1247755b21 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?S=C3=B6ren=20Wrede?= <soerenwrede@gmail.com>
Date: Tue, 22 Jan 2019 09:12:43 -0800
Subject: [PATCH 06/19] Update docs/contributors/readme.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 docs/contributors/readme.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
index 0c6d533779dba..e3979c229e25c 100644
--- a/docs/contributors/readme.md
+++ b/docs/contributors/readme.md
@@ -2,7 +2,7 @@
 
 Welcome to the Gutenberg Project Contributors Guide.
 
-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.
+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.
 
 ## Philosophy
 

From cd05aed7c0a3c003bf9b837cb688b02ec578a1f5 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Tue, 22 Jan 2019 09:18:40 -0800
Subject: [PATCH 07/19] Remove meetups, there are far too many to list, since
 most meetups now all cover Gutenberg in some degree or other

---
 docs/contributors/outreach.md | 18 ------------------
 1 file changed, 18 deletions(-)

diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md
index 873c0af4777f6..f45ef5f4ec92c 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -67,21 +67,3 @@ https://www.meetup.com/WordPress-Melbourne/events/241543639
 
 https://wpmeetups.de/termin/29-wp-meetup-stuttgart-gutenberg-editor-rueckblick-wordcamp-europe/
 
-
-## 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

From 9c4d34c245951423328e0af1d89c36f1f48f3e77 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Tue, 22 Jan 2019 09:57:42 -0800
Subject: [PATCH 08/19] Update CONTRIBUTING with links to Documentation section

---
 CONTRIBUTING.md               | 18 ++----------------
 docs/contributors/document.md | 23 +++++++++++++++++++++++
 2 files changed, 25 insertions(+), 16 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 46a627a35b2da..8b61edbad5cdb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -124,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 create a Markdown file in the [docs](https://github.com/WordPress/gutenberg/tree/master/docs) folder and add an item to the [toc.json](https://github.com/WordPress/gutenberg/blob/master/docs/toc.json) and generate using `npm run docs:build`.
-
-### Using links
+Please see the [Documentation section](/docs/contributors/document.md) of the Contributors Handbook.
 
-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`
-
-This way they will be properly handled in all three aforementioned contexts.
+Documentation is automatically synced from master to the [Gutenberg Documentation Website](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
 
 ### `@wordpress/component`
 
diff --git a/docs/contributors/document.md b/docs/contributors/document.md
index 1f2abfb0ca881..23a0ee52b2e9a 100644
--- a/docs/contributors/document.md
+++ b/docs/contributors/document.md
@@ -2,6 +2,29 @@
 
 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. Generate 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
+
+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`
+
+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.

From 215246f39153714da0956105d2c31fe43e7f0618 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:12:31 -0800
Subject: [PATCH 09/19] Update CONTRIBUTING.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 8b61edbad5cdb..49ed5c6074854 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,7 +4,7 @@ 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 review the [Contributors 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.
+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.
 

From 17ee00c96dc69e99ede2b43cb07a582ec380e502 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:12:44 -0800
Subject: [PATCH 10/19] Update CONTRIBUTING.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 49ed5c6074854..5554cadf3198a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -124,7 +124,7 @@ If you'd like to contribute to the design or front-end, feel free to contribute
 
 ## Contribute to the Documentation
 
-Please see the [Documentation section](/docs/contributors/document.md) of the Contributors Handbook.
+Please see the [Documentation section](/docs/contributors/document.md) of the Contributor Handbook.
 
 Documentation is automatically synced from master to the [Gutenberg Documentation Website](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
 

From 95d183fbd76f40ce111606f26387d5d807672f57 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:13:02 -0800
Subject: [PATCH 11/19] Update CONTRIBUTING.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 CONTRIBUTING.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 5554cadf3198a..576e78b27a3ee 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -126,7 +126,7 @@ If you'd like to contribute to the design or front-end, feel free to contribute
 
 Please see the [Documentation section](/docs/contributors/document.md) of the Contributor Handbook.
 
-Documentation is automatically synced from master to the [Gutenberg Documentation Website](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
+Documentation is automatically synced from `master` to the [Gutenberg Handbook](https://wordpress.org/gutenberg/handbook/) every 15 minutes.
 
 ### `@wordpress/component`
 

From 92c3c23c4fcbcb00c5c7ce9ce4dac72aecdc9560 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:14:06 -0800
Subject: [PATCH 12/19] Update docs/contributors/outreach.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 docs/contributors/outreach.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md
index f45ef5f4ec92c..389bbbf8805fa 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -1,6 +1,6 @@
 # Outreach
 
-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 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.
 
 
 

From 258344e02fa08c0f4a59f1ed021d72e57e63e68b Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:14:27 -0800
Subject: [PATCH 13/19] Update docs/contributors/outreach.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 docs/contributors/outreach.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md
index 389bbbf8805fa..12c6bf5416317 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -6,7 +6,7 @@ This includes articles, talks, demos and anything the community is doing to disc
 
 ## Articles
 
-A short list of useful articles around defining, extending, and contributing to Gutenberg project.
+A short list of useful articles around defining, extending, and contributing to Gutenberg.
 
 ### Overviews of Gutenberg
 

From b593f9bf30da4e551ebb6fc2692e6b02c978b77f Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:15:37 -0800
Subject: [PATCH 14/19] Update docs/contributors/document.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 docs/contributors/document.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/document.md b/docs/contributors/document.md
index 23a0ee52b2e9a..a88add66245ee 100644
--- a/docs/contributors/document.md
+++ b/docs/contributors/document.md
@@ -8,7 +8,7 @@ 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. Generate manifest.json by running `npm run docs:build`
+3. Update manifest.json by running `npm run docs:build`
 4. Commit manifest.json with other files updated
 
 ## Using Links

From 58971faf1cea40acc9e4fee5bf2d69a0be7560e1 Mon Sep 17 00:00:00 2001
From: Chris Van Patten <hello@chrisvanpatten.com>
Date: Wed, 23 Jan 2019 06:24:54 -0800
Subject: [PATCH 15/19] Update docs/contributors/document.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 docs/contributors/document.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/document.md b/docs/contributors/document.md
index a88add66245ee..443019a816fc7 100644
--- a/docs/contributors/document.md
+++ b/docs/contributors/document.md
@@ -18,7 +18,7 @@ It's very likely that at some point you will want to link to other documentation
 - 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:
+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`

From e435858c4e6f5d99fe534cd7ab5de6dc686a339c Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 23 Jan 2019 06:29:07 -0800
Subject: [PATCH 16/19] Add some newlines, take some away

---
 docs/contributors/document.md | 2 ++
 docs/contributors/outreach.md | 4 ----
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/docs/contributors/document.md b/docs/contributors/document.md
index 443019a816fc7..f51578d99e3c3 100644
--- a/docs/contributors/document.md
+++ b/docs/contributors/document.md
@@ -14,11 +14,13 @@ To add a new documentation page:
 ## 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`
diff --git a/docs/contributors/outreach.md b/docs/contributors/outreach.md
index 12c6bf5416317..208a1eaf707e1 100644
--- a/docs/contributors/outreach.md
+++ b/docs/contributors/outreach.md
@@ -2,8 +2,6 @@
 
 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.
@@ -35,8 +33,6 @@ A short list of useful articles around defining, extending, and contributing to
 - [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.

From f220a8c2800c2f668418c852218744d8810f9491 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 23 Jan 2019 06:30:39 -0800
Subject: [PATCH 17/19] Paragraph for resources

---
 docs/contributors/develop.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/contributors/develop.md b/docs/contributors/develop.md
index 93c4cc1b02888..b67a808904936 100644
--- a/docs/contributors/develop.md
+++ b/docs/contributors/develop.md
@@ -2,6 +2,8 @@
 
 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 Grammer](/docs/contributors/grammar.md)
 * [Testing Overview](/docs/contributors/testing-overview.md) for PHP and JavaScript development in Gutenberg.

From 08d118b34b4be42b50a7d731e6b723cec9202f20 Mon Sep 17 00:00:00 2001
From: Marcus Kazmierczak <marcus@mkaz.com>
Date: Wed, 23 Jan 2019 09:05:47 -0800
Subject: [PATCH 18/19] Update title in generator

---
 bin/generate-public-grammar.js | 2 +-
 docs/grammar.md                | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)
 create mode 100644 docs/grammar.md

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/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>

From 27f9cec118a0057dc05db174574ecd5b684ae1ae Mon Sep 17 00:00:00 2001
From: Miguel Fonseca <miguelcsf@gmail.com>
Date: Wed, 23 Jan 2019 09:06:32 -0800
Subject: [PATCH 19/19] Update docs/contributors/develop.md

Co-Authored-By: mkaz <marcus@mkaz.com>
---
 docs/contributors/develop.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/contributors/develop.md b/docs/contributors/develop.md
index b67a808904936..97fa91aab0f78 100644
--- a/docs/contributors/develop.md
+++ b/docs/contributors/develop.md
@@ -5,7 +5,7 @@ Please see [CONTRIBUTING.md](https://github.com/WordPress/gutenberg/blob/master/
 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 Grammer](/docs/contributors/grammar.md)
+* [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.