Update and Organize Contributors Guide per #12916

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,31 +116,17 @@ 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?
 
 If you'd like to contribute to the design or front-end, feel free to contribute to tickets labelled [Needs Design](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3A%22Needs+Design%22) or [Needs Design Feedback](https://github.com/WordPress/gutenberg/issues?q=is%3Aissue+is%3Aopen+label%3A"Needs+Design+Feedback%22). We could use your thoughtful replies, mockups, animatics, sketches, doodles. Proposed changes are best done as minimal and specific iterations on the work that precedes it so we can compare. If you use <a href="https://www.sketchapp.com/">Sketch</a>, you can grab <a href="https://cloudup.com/cMPXM8Va2cy">the source file for the mockups</a> (updated April 6th).
 
 ## 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`
 

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 ) }
 ` );

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,33 +25,33 @@ 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.
 
 Features don’t allow anyone to do anything; they’re just tools that do specific things to achieve an end. Just say what they do:
 
 > 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.”
 
 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.
 
 ## Bulleted Lists
 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,23 +187,23 @@ 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.
 
 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.
 
 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.
 

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.
 

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.

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.

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