Revert "First attempt at some documentation updates"

This reverts commit 4a74468.

Author: kraftbj

docs/monorepo.md

@@ -47,20 +47,19 @@ All projects should be compatible with PHP versions WordPress supports. That's c
 
 First time working with the monorepo? We got you covered.
 
-Install the Jetpack CLI:
+For the first time only:
 
-```bash
-npm install -g @automattic/jetpack-cli
-```
+* From the root of the repo, run `pnpm install && pnpm jetpack cli link` (if you want the `jetpack` CLI tool installed globally) or `pnpm install` (if you don't).
+* That’s it. You won’t need to do that again unless you nuke your node_modules directory.
 
-Once installed, you can run `jp` anywhere in the Jetpack repo. Run `jp --help` to see all available commands.
+Once you’ve done that, it’s easy: run `jetpack` (or `pnpm jetpack`) while anywhere in the Jetpack repo. To explore on your own, run `jetpack --help` to see the available commands.
 
 ## Jetpack Generate Wizard
 
 Starting a new project? Great! Let the Jetpack Generate Wizard help jumpstart the files you need. To get started:
 
 * Make sure you're checked out to the branch you want.
-* Use the CLI command `jp generate` to start the process.
+* Use the CLI command `jetpack generate` to start the process.
 * The wizard will walk you through the steps of starting a new package, plugin, or Github action.
 
 ### Accepted Arguments
@@ -70,7 +69,7 @@ The wizard accepts a few arguments to speed things up:
 * `[project type]` - Accepted values: `package`, `plugin`, `github-action`
 * `--name`, `--n` - The name of your project (no spaces)
 
-Example: `jp generate plugin --name my_cool_plugin` will generate plugin files for a plugin called `my_cool_plugin` under `../jetpack/projects/plugins`
+Example: `jetpack generate plugin --name my_cool_plugin` will generate plugin files for a plugin called `my_cool_plugin` under `../jetpack/projects/plugins`
 
 ### What's Included
 
@@ -457,29 +456,29 @@ The body is separated from the headers by a blank line, and is the text that act
 
 The changelogger tool can be used via [Jetpack's CLI tool](#first-time). You may use the following command to generate changelog entries for each project that needs one:
 
-`jp changelog add`
+`jetpack changelog add`
 
 **Does it matter what the change file is named?** Starting the file name with `.` should not be used. Also consider avoiding names that have extensions like `.php` or `.js` to avoid confusing other tools.
 
-**What if a change is so trivial that it doesn't need a changelog entry?** The change file is still required. If you specify the significance as "patch", changelogger will allow the body section to be empty so as to not generate an entry in the changelog. In this case, use the "Comment" header instead, for example:
+**What if a change is so trivial that it doesn’t need a changelog entry?** The change file is still required. If you specify the significance as “patch”, changelogger will allow the body section to be empty so as to not generate an entry in the changelog. In this case, use the “Comment” header instead, for example:
 
-```bash
+```
 Significance: patch
 Type: compat
 Comment: Update composer.lock, no need for a changelog entry
 ```
 
-**Adding the first PR to a project after a release?** If a PR is the first to Jetpack after a release, version numbers may need to be bumped. This also applies to the first semantic versioning "minor" or "major" change to any projects that use semantic versioning.
+**Adding the first PR to a project after a release?** If a PR is the first to Jetpack after a release, version numbers may need to be bumped. This also applies to the first semantic versioning “minor” or “major” change to any projects that use semantic versioning.
 
-The "Linting / Changelogger validity" GitHub Actions check will help in making sure that all these version numbers are in sync with the version inferred from the changelog and change files. You can also check this locally with `tools/changelogger-validate-all.sh`.
+The “Linting / Changelogger validity” GitHub Actions check will help in making sure that all these version numbers are in sync with the version inferred from the changelog and change files. You can also check this locally with `tools/changelogger-validate-all.sh`.
 
-Within a single project, changlogger's `version next` command can tell you the next version, and the monorepo script `tools/project-version.sh` can be used to check and update the version numbers.
+Within a single project, changlogger’s `version next` command can tell you the next version, and the monorepo script `tools/project-version.sh` can be used to check and update the version numbers.
 
 ## New Projects
 
 To begin,
 * For Automatticians, drop us a line in #jetpack-crew to discuss your needs, just to be sure we don't have something already. For others, it would probably be best to open an issue to discuss it.
-* Use the `jp generate` command to create a skeleton project.
+* Use the `jetpack generate` command to create a skeleton project.
 * Create your project based on the skeleton and submit a PR as usual.
 
 Once we're sure that the project will be created and what its name will be, someone (you or the Crew team) does the following:

docs/quick-start.md

@@ -2,93 +2,116 @@
 
 ## Overview
 
-This guide will get you up and running with Jetpack development as quickly as possible using our recommended tools.
+This guide is designed to get you up and running working with the Jetpack Monorepo quickly following recommended and supported guidelines.
 
-**Prerequisites**: You'll need:
-- Node.js installed (any recent LTS version)
-- Git installed and configured
-- Docker installed and running
+**This guide assumes you are using MacOS or a Linux machine and are an Automattician**. For more detailed information, including setting up local dev environments for all contributors, running unit tests, best coding practices, and more, you can use the [full Development Environment guide here](development-environment.md#clone-the-repository).
 
 ## Installation
 
-1. Install the Jetpack CLI:
-```bash
-npm install -g @automattic/jetpack-cli
-```
+### Using the installation script
 
-2. Initialize Jetpack:
-```bash
-jp init
-```
+To speed up the installation process, you may use our monorepo installation script. To do so:
 
-This will:
-- Clone the Jetpack monorepo to your chosen location
-- Guide you through the next steps to get started
+- Clone the Jetpack Monorepo:
+	- Using a public SSH key ([recommended](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)): `git clone [email protected]:Automattic/jetpack.git` 
+		- Or use HTTPS: `git clone https://github.com/Automattic/jetpack.git` 
+	- Note that the monorepo should not be cloned into the WordPress plugins directory. If you plan on not using the provided Docker environment, read the [full Development Environment guide here](development-environment.md#clone-the-repository) to find out how to add symlinks.
+- `cd` into the cloned `jetpack` folder.
+- Run `tools/install-monorepo.sh` from the monorepo root.
+- You can use the [environment checker script](#check-if-your-environment-is-ready-for-jetpack-development) to confirm that all required tools are installed.
 
-## Development Workflow
+Once the installation is complete, continue onto the section [Running Jetpack locally](#running-jetpack-locally).
 
-Build and test your changes:
-```bash
-# Build a specific project with dependencies
-jp build plugins/jetpack --deps
+### Installing manually
 
-# Or watch for changes
-jp watch plugins/jetpack
+Prior to installation, we recommend using [`Homebrew`](https://brew.sh/) to manage installations and [`nvm`](https://github.com/nvm-sh/nvm/) to manage Node.js versions. If you don't already have those installed, you can do so by copy/pasting each of the following commands and running them in your terminal:
 
-# Run tests
-jp test
-```
+- Homebrew: `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`
+- nvm: `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash`
 
-## Testing with Docker
+The Jetpack Monorepo requires various software to be installed on your machine.
 
-Jetpack includes a testing environment using Docker. To start testing:
+- Clone the Jetpack Monorepo:
+ 	- Using a public SSH key ([recommended](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account)): `git clone [email protected]:Automattic/jetpack.git`
+		- Or use HTTPS: `git clone https://github.com/Automattic/jetpack.git`
+	- Note that the monorepo should not be cloned into the WordPress plugins directory. If you plan on not using the provided Docker environment, read the [full Development Environment guide here](development-environment.md#clone-the-repository) to find out how to add symlinks.
+- This software needs to be installed or updated system-wide:
+	- Bash (will need to be updated from default Mac version): `brew install bash`
+	- jq (JSON processor used in scripts): `brew install jq` 
+- To install or update the following software, cd into the Jetpack directory that was created when cloning the repo: `cd jetpack`:
+	- Node.js (used for build process and our CLI): `nvm install && nvm use`
+	- PNPM (a Node.js package manager): `npm install -g pnpm`
+	- PHP (the language at the core of the WordPress ecosystem): `source .github/versions.sh && brew install php@$PHP_VERSION`
+	- Composer (our PHP package manager): `brew install composer`
+	- Jetpack CLI (an internal tool that assists with development): `pnpm install && pnpm jetpack cli link`
+		- [You can read more about using the CLI here](https://github.com/Automattic/jetpack/blob/trunk/tools/cli/README.md).
 
-1. Start the testing environment:
-```bash
-jp docker up -d
-```
+### Check if your environment is ready for Jetpack development
 
-2. Install WordPress (first time only):
-```bash
-jp docker install
+We provide a script to help you in assessing if everything's ready on your system to contribute to Jetpack.
+
+```sh
+tools/check-development-environment.sh
 ```
 
-3. Visit http://localhost to see your site!
+Running the script will tell you if you have your environment already set up and what you need to do in order to get it ready for Jetpack development:
 
-## Testing WordPress.com Features
+- All green `YES` or `OK` messages mean you're ready to start
+- Red `NO` messages mean something is wrong or missing, and a link will be provided to help you with a fix.
+- Yellow messages indicate something optional is broken or missing.
 
-To test features requiring a WordPress.com connection:
+## Running Jetpack locally
 
-### For Automatticians:
-Use Jurassic Tube:
-```bash
-jp docker jt-up
-```
+After everything is installed, you're ready to run Jetpack locally! While there are other supported methods of doing this, we recommend and support using Docker containers. 
 
-### For External Contributors:
-Use ngrok:
-```bash
-jp docker ngrok-up
-```
+To setup Docker:
+- Install Docker:
+	- Mac: `brew install --cask docker` (This will take a while!)
+	- Linux: `brew install docker` 
+	- `open -a Docker` (or open the app from your Applications folder) to open the GUI application. You will likely need to enter your device password and accept their terms for a first time setup.
+- Copy the settings file from within the monorepo root: `cp tools/docker/default.env tools/docker/.env`
+- Open `tools/docker/.env` and make any modifications you'd like.	
+	- It's strongly recommend you at least change `WP_ADMIN_PASSWORD` to something more secure.
+- Start the Docker container using `jetpack docker up -d` (this may take some time for the first setup)
+- Install WordPress in your Docker container using `jetpack docker install` 
+- Open up http://localhost to see your site!
+
+For more in depth Docker instructions, follow the [Docker environment for Jetpack Development guide](../tools/docker/README.md).
 
 ## Setting up Jurassic Tube
 
 In order to test features that require a WordPress.com connection and other network related Jetpack features, you'll need a test site that can create local HTTP tunnels. If you're an Automattician, we recommend using Jurassic Tube.
 
 Note: This is for Automattician use only. For other methods, check out [ngrok](../tools/docker/README.md#using-ngrok-with-jetpack) or [another similar service](https://alternativeto.net/software/ngrok/).
 
-**Warning: This creates a tunnel to your local machine which should not be trusted as secure. If it is compromised, so is your computer and everything it has access to. Only `jp docker jt-up` when needed for testing things that require 
-the site to be publicly accessible, and `jp docker jt-down` when completed.**
+**Warning: This creates a tunnel to your local machine which should not be trusted as secure. If it is compromised, so is your computer and everything it has access to. Only `jetpack docker jt-up` when needed for testing things that require the site to be publicly accessible, and `jetpack docker jt-down` when completed.**
 
 - Visit the [jurassic.tube](https://jurassic.tube/) homepage to create a subdomain
-- Make sure you've run `npm install -g @automattic/jetpack-cli`
-- Make sure Docker is running `jp docker up -d`
+- Make sure you've run `pnpm install && pnpm jetpack cli link`
+- Make sure Docker is running `jetpack docker up -d`
 - Stand on the monorepo root in your terminal and run `mkdir tools/docker/bin/jt`
-- Stop and restart the docker env: `jp docker stop && jp docker up -d`
+- Stop and restart the docker env: `jetpack docker stop && jetpack docker up -d`
 - Download and run the installation script: `curl "https://jurassic.tube/get-installer.php?env=jetpack" -o tools/docker/bin/jt/installer.sh && chmod +x tools/docker/bin/jt/installer.sh && tools/docker/bin/jt/installer.sh`
-- Set your username: `jp docker jt-config username [your-username-here e.g david]`
-- Set your subdomain: `jp docker jt-config subdomain [your-subdomain-here e.g. spaceman]` 
-- Now, you can start your site with `jp docker jt-up`
+- Set your username: `jetpack docker jt-config username [your-username-here e.g david]`
+- Set your subdomain: `jetpack docker jt-config subdomain [your-subdomain-here e.g. spaceman]` 
+- Now, you can start your site with `jetpack docker jt-up`
 - Your site should be available at `https://custom-subdomain.jurassic.tube`
 
-That's all! For more detailed information, see the [Development Environment guide](development-environment.md).
+## Development Workflow
+
+Once you have a local copy of Jetpack and all development tools installed, you can start developing.
+
+1. Make sure the plugin you're developing is activated on your WordPress site.
+2. [Build your project](development-environment.md#building-your-project) using `jetpack build [type/project]` and including its dependencies, such as `jetpack build plugins/jetpack --deps`
+3. Access the plugin's dashboard in your browser.
+
+By default the development build above will run once and if you change any of the files, you need to run `jetpack build` again to see the changes on the site. If you want to avoid that, you can run a continuous build that will rebuild anytime it sees any changes on your local filesystem. To run it, use:
+
+```sh
+jetpack watch
+```
+### Running Tests
+
+To run PHP, JS, and coverage tests, you can use the Jetpack CLI: `jetpack test` and then choose the project and type of test you'd like to run.
+
+That's all!