Blueprints Crash Course (#5)

Launching this Blueprint community space hinges on good materials to
explain what Blueprints are and how developers can work with them.

This PR proposes a few pages to cover:

1. What are Blueprints and how are they useful?
2. How to run Blueprints
3. Building your first Blueprint
4. Debugging Blueprints
5. Developer Tools
6. More Resources

It's a loose interpretation of [the previously proposed
outline](WordPress/blueprints-library#64) that
covers roughly the same topics in a lean way.

## Reviewing

[<kbd> <br>Preview proposed
documentation<br> </kbd>](https://github.com/adamziel/blueprints/blob/blueprints-crash-course/docs/index.md)

cc @flexseth @bph @jonathanbossenger @ironnysh @westnz @justintadlock
@annezazu @bgrgicak @brandonpayton @dmsnell for your opinions. I'd love
to learn:

1. Do you think this covers enough to launch the Community Space and
iterate later?
2. Are these pages clear? Do they do a good job of getting a person from
0 to familiar?
3. What would you change?

## Documentation format

This PR uses Markdown because it's easy to write and can be readily
previewed on GitHub.

In parallel, we're exploring [a Playground-based documentation writing
workflow](https://github.com/adamziel/playground-docs-workflow). It's
not ready for production use yet and I didn't want to block the
community space on these explorations. Once it's finished, these docs
should be easy to migrate.

Closes #2

---------

Co-authored-by: Ronny Shani <63248335+ironnysh@users.noreply.github.com>
Co-authored-by: Birgit Pauli-Haack <birgit.pauli@gmail.com>

CONTRIBUTING.md

@@ -1,34 +1,33 @@
-## Contributing Guidelines
+# Contribution Guidelines
 
 We encourage you to contribute your own Blueprints to this repository!
 
-### Building your first Blueprint
+## Build your first Blueprint
 
-See [Building your first Blueprint](./docs/how-to-build-a-blueprint/your-first-blueprint.md).
+Not sure how? Check out the [Blueprints 101](./docs/index.md).
 
-### Submitting your Blueprint to this repository
+## Submit your Blueprint to this repository
 
-To keep the submission process smooth, please follow the following guidelines:
+To keep the submission process smooth, please follow these guidelines:
 
-Submit your Blueprint as a Pull Request to this repository.
+1. Submit [a Pull Request (PR)](https://github.com/adamziel/blueprints/pulls) with your Blueprint.
+2. The PR must contain a single `blueprint.json` file under the path `blueprints/your-blueprint-name/blueprint.json` (like [the examples here](https://github.com/adamziel/blueprints/tree/trunk/blueprints)).
+3. Include all static files (WXR, ZIP, JPG, etc.) listed in the Blueprint in the submitted directory of your PR, and reference them via the `https://raw.githubusercontent.com` domain.
+4. By submitting a Blueprint, you agree to license it under [GPLv2 or later license](https://www.gnu.org/licenses/old-licenses/gpl-2.0.en.html).
 
-Your Pull Request must contain a single `blueprint.json` file under a path `blueprints/your-blueprint-name/blueprint.json`.
+## Blueprint metadata
 
-All static files (WXR, ZIP, JPG etc.) referenced by the Blueprint must be included in the submitted directory in your Pull Request and referenced via the `raw.githubusercontent.com` domain.
+Each Blueprint should include metadata within the top-level "meta" key of the `blueprint.json` file.
 
-By submitting a Blueprint, you agree to license it under GPLv2 or later license.
+Here's what's required:
 
-### Blueprint Metadata
+- **Title:** a clear and concise name for your Blueprint.
+- **Author:** your GitHub username, to let others know who created the Blueprint.
 
-Each Blueprint should include some basic metadata within the top-level "meta" key in the blueprint.json file. Here's what's required:
+Optionally, you can add:
 
-* Title: A clear and concise name for your Blueprint.
-* Author (GitHub Username): Let others know who created the Blueprint.
-
-Optionally, you can also include:
-
-* Description: Provide a brief explanation of what your Blueprint offers.
-* Categories: Specify relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org.
+- **Description:** a brief explanation of what the Blueprint offers.
+- **Categories:** specify relevant categories to help users find your Blueprint in the future Blueprints section on WordPress.org.
 
 Here's an example:
 
@@ -43,6 +42,6 @@ Here's an example:
 }
 ```
 
-### Needing Help?
+## Need help?
 
-If you have questions or need assistance, start a new issue in this repository.
+If you have questions or comments, [open a new issue](https://github.com/adamziel/blueprints/issues) in this repository.

GALLERY.md

@@ -1,6 +1,8 @@
 # WordPress Blueprints Gallery
 
-Here's the list of all the community Blueprints submitted to this repository. See the [contribution guidelines](./README.md#contributing-your-blueprint) to submit your Blueprint and share your WordPress setup with the world!
+Here are all the community Blueprints submitted to this repository.
+
+Want to share your WordPress setup with the world? See the [contribution guidelines](./CONTRIBUTING.md) for more information on how to submit your Blueprint.
 
 | Title                               | Preview                                                                                                                                                           | Source                                                                                                 |
 | -----                               | -------                                                                                                                                                           | ------                                                                                                 |

README.md

@@ -5,7 +5,11 @@
 
 ## What are Blueprints?
 
-Blueprints are WordPress setup descriptions that can be previewed live in [WordPress Playground](https://w.org/playground). Just like this one:
+Check out [Blueprints 101](./docs/index.md) to get started.
+
+Here's a quick overview:
+
+Blueprints are WordPress setup scripts that you can preview live in [WordPress Playground](https://w.org/playground). Here's a simple example:
 
 ```json
 {
@@ -17,31 +21,33 @@ Blueprints are WordPress setup descriptions that can be previewed live in [WordP
 
 [<kbd> <br> Preview in WordPress Playground <br> </kbd>](https://playground.wordpress.net/#%7B%22plugins%22:%5B%22hello-dolly%22,%22gutenberg%22%5D,%20%22login%22:%20true,%20%22landingPage%22:%20%22/wp-admin/plugins.php%22%20%7D)
 
-Blueprints contain all the setup information including plugins, themes, site options, starter content to import, and more. See [Building your first Blueprint](./docs/how-to-build-a-blueprint/your-first-blueprint.md) for more details.
+Blueprints contain all the installation instructions needed to setup WordPress, including plugins, themes, site options, starter content to import, and more.
+
+Check out [Blueprints 101](./docs/index.md) to get started with Blueprints.
 
 ## Why use Blueprints?
 
-Blueprints can help you:
+Blueprints can help you
 
-* Explore different setups – Try out different themes and plugins without the risk of breaking your site. It's a safe environment to see what works best for your needs.
-* Save time – Instead of manually setting up your site, choosing themes, and installing plugins one by one, Blueprints do all that work for you in a few clicks.
-* Learn WordPress – Blueprints are a fantastic way to play with a variety of WordPress configurations.
+- **Explore different setups:** try out different themes and plugins without the risk of breaking your site. It's a safe environment to see what works best for your needs.
+- **Save time**:** instead of manually setting up your site, choosing themes, and installing plugins one by one, Blueprints do all work for you.
+- **Learn WordPress:** Blueprints are a fantastic way to play with a variety of WordPress configurations.
 
 ## Ready to jump in?
 
-In this community space, you can:
+This community space allows you to
 
-* [Browse the Blueprints Gallery](./GALLERY.md) to explore a variety of WordPress sites.
-* [Submit your own Blueprint](./CONTRIBUTING.md) to share your WordPress setup with the community.
+* [Browse the Blueprints Gallery](./GALLERY.md) and explore diverse WordPress sites.
+* [Submit your own Blueprint](./CONTRIBUTING.md) and share your WordPress setup with the community.
 
 ## Contributing your Blueprint
 
-We encourage you to contribute your own Blueprints to this repository! New submissions are accepted as Pull Requests, for more details consult [Contributing Guidelines](./CONTRIBUTING.md)
+We encourage you to contribute your Blueprints to this repository! We accepet new submissions as Pull Requests. Read the [Contributing Guidelines](./CONTRIBUTING.md) for more details. 
 
-## Needing Help?
+## Need help?
 
-If you have questions or need assistance, start a new issue in this repository.
+If you have questions or comments, [open a new issue](https://github.com/adamziel/blueprints/issues) in this repository.
 
-## Let's Build the Blueprint Community Together!
+## Let's build the Blueprint Community together!
 
-This is a minimal version 1 (v1) to get the community space up and running quickly. We plan to build upon this foundation based on your feedback. So, explore, create, and share your Blueprints!
+This is a minimal version 1 (v1) to get the community space up and running. We plan to build upon this foundation, expand, and improve it—with your feedback. So, explore, create, and share your Blueprints!

blueprints/grid-variations/blueprint.json

@@ -2,8 +2,8 @@
     "$schema": "https://playground.wordpress.net/blueprint-schema.json",
     "meta": {
         "title": "Grid Variations Experiments enabled",
-        "description": "Blueprint example to toggle on enable a feature from the Experiments page in Gutenberg plugin",
         "author": "bph",
+        "description": "Blueprint example to toggle on enable a feature from the Experiments page in Gutenberg plugin",
         "categories": ["Gutenberg", "Experiments"]
     },
     "landingPage": "/wp-admin/site-editor.php",

blueprints/latest-gutenberg/blueprint.json

@@ -1,8 +1,8 @@
 {
 	"meta": {
 		"title": "Latest Gutenberg plugin",
-		"description": "A preview of the latest version of the Gutenberg plugin.",
 		"author": "zieladam",
+		"description": "A preview of the latest version of the Gutenberg plugin.",
 		"categories": ["plugins"]
 	},
 	"plugins": ["gutenberg"]