Documentation: Organize Contributors Guide (#19853)

* Simplify CONTRIBUTING.md to be just guidelines We don't need to include too much here because the real information for contributing is in the handbook. This page is a standard page for Github repos, so trimming it down to just a few links to sections in the handbook. Plus the policies for code of conduct and GPL. * Add design contribution from CONTRIBUTING.md to design page * Cleanup and organize Contributors Guide * Use consistent Contributors Guide title * Move Principles and catch-all docs to Project Overview section * Switch background to more relevant repository management * Apply suggestions from code review Thanks for the fixes 👍 Co-Authored-By: Chris Van Patten <[email protected]> * Fix extra newlines * Standardize on Contributor Guide, matches core handbook * Update manifest Co-authored-by: Chris Van Patten <[email protected]>
WordPress · Jan 27, 2020 · ba2495f · ba2495f
1 parent 9e3c713
commit ba2495f
Show file tree

Hide file tree

Showing 6 changed files with 110 additions and 102 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,38 +1,24 @@
-# Contributing
+# Contributing Guidelines
 
-Thank you for thinking about contributing to WordPress' Gutenberg project! If you're unsure of anything, know that you're 💯 welcome to submit an issue or pull request on any topic. The worst that can happen is that you'll be politely directed to the best location to ask your question or to change something in your pull request. We appreciate any sort of contribution and don't want a wall of rules to get in the way of that.
+Welcome to WordPress' Gutenberg project! We hope you join us in creating the future platform for publishing; all are welcome here.
 
-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).
+## How can I contribute?
 
-Before contributing, we encourage you to review the [Contributor Handbook](https://developer.wordpress.org/block-editor/contributors/). If you have any questions, please ask, either in Slack or open an issue in GitHub so we can help clarify.
+To learn all about contributing to the Gutenberg project, see the [Contributor Guide](/docs/contributors/readme.md). The handbook includes all the details you need to get setup and start shaping the future of web publishing.
 
-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.
+- Code? See the [developer section](/docs/contributors/develop.md).
 
-This document covers the technical details around setup, and submitting your contribution to the Gutenberg project.
+- Design? See the [design section](/docs/contributors/design.md).
 
-## Developer Contributions
+- Documentation? See the [documentation section](/docs/contributors/document.md).
 
-Please see the [Developer Contributions section](/docs/contributors/develop.md) of the Contributor Handbook.
+- Triage? We need help reviewing existing issues to make sure they’re relevant and actionable. Triage is an important contribution because it allows us to work on the highest priority issues. To learn more, please see the [triaging issues section](docs/contributors/repository-management.md#triaging-issues).
 
-## How Can Designers Contribute?
+## Guidelines
 
-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. The [WordPress Design team](http://make.wordpress.org/design/) uses [Figma](https://www.figma.com/) to collaborate and share work. If you'd like to contribute, join the [#design channel](http://wordpress.slack.com/messages/design/) in [Slack](https://make.wordpress.org/chat/) and ask the team to set you up with a free Figma account. This will give you access to a helpful [library of components](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=0%3A1) used in WordPress.
+- 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).
 
-## Triage Contributions
-
-*Triage* is the practice of reviewing existing issues to make sure they’re relevant, actionable, and have all the information needed to reproduce and/or solve the issue. Triaging is a very important contribution because it allows the community to focus on and prioritise issues, feature proposals, discussions, and so on.
-
-If you want to learn more about triage, and why it it important, please see the [repository management section](docs/contributors/repository-management.md#triaging-issues) of the Contributor Handbook.
-
-## Contribute to the Documentation
-
-Please see the [Documentation section](/docs/contributors/document.md) of the Contributor Handbook.
-
-Documentation is automatically synced from `master` to the [Block Editor Handbook](https://developer.wordpress.org/block-editor/) every 15 minutes.
-
-### `@wordpress/components`
-
-If you're contributing to the documentation of any component from the `@wordpress/components` package, take a look at its [guidelines for contributing](/packages/components/CONTRIBUTING.md).
+- 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.
 
 ## Reporting Security Issues
 

diff --git a/docs/contributors/design.md b/docs/contributors/design.md
@@ -2,6 +2,12 @@
 
 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.
 
+## 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.
+
+The [WordPress Design team](http://make.wordpress.org/design/) uses [Figma](https://www.figma.com/) to collaborate and share work. If you'd like to contribute, join the [#design channel](http://wordpress.slack.com/messages/design/) in [Slack](https://make.wordpress.org/chat/) and ask the team to set you up with a free Figma account. This will give you access to a helpful [library of components](https://www.figma.com/file/ZtN5xslEVYgzU7Dd5CxgGZwq/WordPress-Components?node-id=0%3A1) used in WordPress.
+
 ## Principles
 
 ![Gutenberg Logo](https://cldup.com/J2MgjuShPv-3000x3000.png)

diff --git a/docs/contributors/principles.md b/docs/contributors/principles.md
@@ -1,4 +1,4 @@
-# Principles
+# Project Overview
 
 First, let’s look at the big picture. If the architectural and UX principles described here are activated at scale, how will the Gutenberg project improve and transform both users and creators experiences?
 

diff --git a/docs/contributors/readme.md b/docs/contributors/readme.md
@@ -1,18 +1,33 @@
-# Contributor Documentation
+# Contributor Guide
 
-Welcome to the Gutenberg Project Contributors Guide.
+Welcome to the Gutenberg Project Contributor Guide. This guide is here to help you get setup and start contributing to the project. If you have any questions, you'll find us in the #core-editor channel in the WordPress Core Slack, [free to join](https://make.wordpress.org/chat/).
 
-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.
+Gutenberg is a sub-project of Core WordPress. Please see the [Core Contributor Handbook](https://make.wordpress.org/core/handbook/) for additional information.
 
-## Philosophy
+## Sections
 
-* [Architectural and UX Principles of Gutenberg](/docs/contributors/principles.md)
+Find the section below based on what you are looking to contribute:
 
-## Sections
+- Code? See the [developer section](/docs/contributors/develop.md).
+
+- Design? See the [design section](/docs/contributors/design.md).
+
+- Documentation? See the [documentation section](/docs/contributors/document.md)
+
+- Triage Support? See the [triaging issues section](/docs/contributors/repository-management/#triaging-issues)
+
+- Internationalization? See the [localizing and translating section](/docs/contributors/localizing.md)
+
+### Repository Management
+
+The Gutenberg project uses Github for managing code and tracking issues. Please see the following sections for the project methodologies using Github.
+
+- [Issue Management](/docs/contributors/repository-management.md#issues)
+
+- [Pull Requests](/docs/contributors/repository-management.md#pull-requests)
 
-The contributors guide has the following different sections by contribution type:
+- [Teams and Projects](/docs/contributors/repository-management.md#teams)
 
-* [Design Contributions](/docs/contributors/design.md)
-* [Developer Contributions](/docs/contributors/develop.md)
-* [Documentation Contributions](/docs/contributors/document.md)
+## Guidelines
 
+See the [Contributing Guidelines](https://github.com/WordPress/gutenberg/blob/master/CONTRIBUTING.md) for the rules around contributing: This includes the code of conduct and licensing information.
diff --git a/docs/manifest-devhub.json b/docs/manifest-devhub.json
@@ -5,11 +5,41 @@
 		"markdown_source": "../docs/readme.md",
 		"parent": null
 	},
+	{
+		"title": "Project Overview",
+		"slug": "principles",
+		"markdown_source": "../docs/contributors/principles.md",
+		"parent": null
+	},
 	{
 		"title": "Key Concepts",
 		"slug": "key-concepts",
 		"markdown_source": "../docs/designers-developers/key-concepts.md",
-		"parent": null
+		"parent": "principles"
+	},
+	{
+		"title": "Glossary",
+		"slug": "glossary",
+		"markdown_source": "../docs/designers-developers/glossary.md",
+		"parent": "principles"
+	},
+	{
+		"title": "Frequently Asked Questions",
+		"slug": "faq",
+		"markdown_source": "../docs/designers-developers/faq.md",
+		"parent": "principles"
+	},
+	{
+		"title": "History",
+		"slug": "history",
+		"markdown_source": "../docs/contributors/history.md",
+		"parent": "principles"
+	},
+	{
+		"title": "Outreach",
+		"slug": "outreach",
+		"markdown_source": "../docs/contributors/outreach.md",
+		"parent": "principles"
 	},
 	{
 		"title": "Developer Documentation",
@@ -234,35 +264,11 @@
 		"parent": "designers"
 	},
 	{
-		"title": "Contributor Documentation",
+		"title": "Contributor Guide",
 		"slug": "contributors",
 		"markdown_source": "../docs/contributors/readme.md",
 		"parent": null
 	},
-	{
-		"title": "Principles",
-		"slug": "principles",
-		"markdown_source": "../docs/contributors/principles.md",
-		"parent": "contributors"
-	},
-	{
-		"title": "Design Principles & Vision",
-		"slug": "design",
-		"markdown_source": "../docs/contributors/design.md",
-		"parent": "contributors"
-	},
-	{
-		"title": "Blocks are the Interface",
-		"slug": "the-block",
-		"markdown_source": "../docs/contributors/principles/the-block.md",
-		"parent": "design"
-	},
-	{
-		"title": "Reference",
-		"slug": "reference",
-		"markdown_source": "../docs/contributors/reference.md",
-		"parent": "design"
-	},
 	{
 		"title": "Developer Contributions",
 		"slug": "develop",
@@ -317,18 +323,30 @@
 		"markdown_source": "../docs/contributors/release.md",
 		"parent": "develop"
 	},
-	{
-		"title": "Localizing Gutenberg Plugin",
-		"slug": "localizing",
-		"markdown_source": "../docs/contributors/localizing.md",
-		"parent": "develop"
-	},
 	{
 		"title": "React Native based mobile Gutenberg",
 		"slug": "native-mobile",
 		"markdown_source": "../docs/contributors/native-mobile.md",
 		"parent": "develop"
 	},
+	{
+		"title": "Design Principles & Vision",
+		"slug": "design",
+		"markdown_source": "../docs/contributors/design.md",
+		"parent": "contributors"
+	},
+	{
+		"title": "Blocks are the Interface",
+		"slug": "the-block",
+		"markdown_source": "../docs/contributors/principles/the-block.md",
+		"parent": "design"
+	},
+	{
+		"title": "Reference",
+		"slug": "reference",
+		"markdown_source": "../docs/contributors/reference.md",
+		"parent": "design"
+	},
 	{
 		"title": "Documentation Contributions",
 		"slug": "document",
@@ -342,21 +360,9 @@
 		"parent": "document"
 	},
 	{
-		"title": "History",
-		"slug": "history",
-		"markdown_source": "../docs/contributors/history.md",
-		"parent": "contributors"
-	},
-	{
-		"title": "Glossary",
-		"slug": "glossary",
-		"markdown_source": "../docs/designers-developers/glossary.md",
-		"parent": "contributors"
-	},
-	{
-		"title": "Frequently Asked Questions",
-		"slug": "faq",
-		"markdown_source": "../docs/designers-developers/faq.md",
+		"title": "Localizing Gutenberg Plugin",
+		"slug": "localizing",
+		"markdown_source": "../docs/contributors/localizing.md",
 		"parent": "contributors"
 	},
 	{
@@ -365,12 +371,6 @@
 		"markdown_source": "../docs/contributors/repository-management.md",
 		"parent": "contributors"
 	},
-	{
-		"title": "Outreach",
-		"slug": "outreach",
-		"markdown_source": "../docs/contributors/outreach.md",
-		"parent": "contributors"
-	},
 	{
 		"title": "Tutorials",
 		"slug": "tutorials",

diff --git a/docs/toc.json b/docs/toc.json
@@ -1,6 +1,13 @@
 [
 	{ "docs/readme.md": [] },
-	{ "docs/designers-developers/key-concepts.md": [] },
+
+	{ "docs/contributors/principles.md": [
+		{ "docs/designers-developers/key-concepts.md": [] },
+		{ "docs/designers-developers/glossary.md": [] },
+		{ "docs/designers-developers/faq.md": [] },
+		{ "docs/contributors/history.md": [] },
+		{ "docs/contributors/outreach.md": [] }
+	] },
 	{ "docs/designers-developers/developers/README.md": [
 		{ "docs/designers-developers/developers/block-api/README.md": [
 			{ "docs/designers-developers/developers/block-api/block-registration.md": [] },
@@ -46,11 +53,6 @@
 		{ "docs/designers-developers/designers/animation.md": [] }
 	] },
 	{ "docs/contributors/readme.md": [
-		{ "docs/contributors/principles.md": [] },
-		{ "docs/contributors/design.md": [
-			{ "docs/contributors/principles/the-block.md": [] },
-			{ "docs/contributors/reference.md": [] }
-		] },
 		{ "docs/contributors/develop.md": [
 			{ "docs/contributors/getting-started.md": [] },
 			{ "docs/contributors/git-workflow.md": [] },
@@ -60,17 +62,17 @@
 			{ "docs/contributors/scripts.md": [] },
 			{ "docs/contributors/managing-packages.md": [] },
 			{ "docs/contributors/release.md": [] },
-			{ "docs/contributors/localizing.md": [] },
 			{ "docs/contributors/native-mobile.md": [] }
 		] },
+		{ "docs/contributors/design.md": [
+			{ "docs/contributors/principles/the-block.md": [] },
+			{ "docs/contributors/reference.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/outreach.md": [] }
+		{ "docs/contributors/localizing.md": [] },
+		{ "docs/contributors/repository-management.md": [] }
 	] },
 	{ "docs/designers-developers/developers/tutorials/readme.md": [
 		{ "docs/designers-developers/developers/tutorials/javascript/readme.md": [
@@ -90,7 +92,6 @@
 			{ "docs/designers-developers/developers/tutorials/block-tutorial/creating-dynamic-blocks.md": [] },
 			{ "docs/designers-developers/developers/tutorials/block-tutorial/generate-blocks-with-wp-cli.md": [] },
 			{ "docs/designers-developers/developers/tutorials/block-tutorial/nested-blocks-inner-blocks.md": [] }
-
 		] },
 		{ "docs/designers-developers/developers/tutorials/metabox/readme.md": [
 			{ "docs/designers-developers/developers/tutorials/metabox/meta-block-1-intro.md": [] },