edit of the Getting Started topics

docs/faqs.md

@@ -4,45 +4,45 @@ title: FAQs
 
 ## Why Node?
 
-There are a number of reasons why Node is the best choice for writing CLI code. At Salesforce, we've released the heroku CLI in Ruby, Go, as well as Node. [This article gets more into detail on that history](https://blog.heroku.com/evolution-of-heroku-cli-2008-2017), but we've certainly found that Node offers the best of everything.
+There are a number of reasons why Node is the best choice for writing CLI code. At Salesforce, we've released the Heroku CLI in Ruby, Go, as well as Node. [Read this article for details on that history](https://blog.heroku.com/evolution-of-heroku-cli-2008-2017). But in the end, we found that Node offers the best of everything.
 
-First, JavaScript is the biggest language in the world. More people are able to write JavaScript than any other language and it by far has the biggest open source community. Everyone can write it and you'll find the most helpful libraries to help build your CLI.
+First, JavaScript is the biggest language in the world. More people write in JavaScript than in any other programming language, and it has the biggest open-source community, by far. Because everyone can write it, you can find many useful libraries to help build your CLI.
 
-We've found that Node has the best cross platform support of any language we've used. In general, if you write code on macOS, you won't find many issues making it also run on Windows.
+We've also found that Node has the best cross-platform support of any language we've used. In general, if you write code on macOS, you rarely find issues making it also run on Windows.
 
-Node has the best support for our [plugins](plugins.md) model. Plugins are a way to share code between CLIs, to modularize a CLIs codebase, or allow users to add functionality to an existing CLI. With Node, we're able to have separate dependency versions sitting alongside one another. This means if you want to release an update to a dependency in one plugin, it won't affect how another plugin works. oclif takes this to an extreme and even flag parsing is done at the individual plugin level. If we ever want to make a breaking change to flag parsing (we certainly don't intend to, but this is just an example), you can update just one plugin and keep the old behavior in other plugins. This is very helpful for large CLI codebases where you want to migrate to new code slowly.
+Node has the best support for our [plugins](plugins.md) model. Plugins are a way to share code between CLIs, to modularize a CLI's codebase, and to allow users to add functionality to an existing CLI. With Node, we can have separate dependency versions sitting alongside one another. As a result, if you want to release an update to a dependency in one plugin, it doesn't affect how another plugin works. oclif takes this to an extreme so that even flag parsing is done at the individual plugin level. For example, if we ever want to make a breaking change to flag parsing (don't worry, we don't intend to!), you can update just one plugin and keep the old behavior in other plugins. This feature is very helpful for large CLI codebases where you want to migrate to new code slowly.
 
-## I want a single binary CLI like with Go
+## How can I create a single binary CLI, like with Go? 
 
-Use [pkg](https://github.com/zeit/pkg). Just make sure to add the commands and other source files by setting `pkg.scripts: "./lib/**/*.js"` in `package.json`.
+Use [pkg](https://github.com/zeit/pkg). Make sure you add the commands and other source files by setting `pkg.scripts: "./lib/**/*.js"` in `package.json`.
 
-In the Salesforce CLI, however, we prefer to ship a tarball (and various installers) that has Node baked in. Use `oclif pack` to create a set of tarballs for different platforms with Node built in. You'll likely need to use [@oclif/plugin-update](https://github.com/oclif/plugin-update) with this, otherwise the users won't have a way to update the CLI from the tarball without reinstalling it.
+In Salesforce CLI, however, we prefer to ship a tarball and various installers that have Node baked in. Use `oclif pack` to create a set of tarballs for different platforms with Node built in. You probably must use [@oclif/plugin-update](https://github.com/oclif/plugin-update) in your CLI, otherwise the users won't have a way to update the CLI from the tarball without reinstalling it.
 
 ## Should I use TypeScript or JavaScript?
 
-We suggest TypeScript as we find the typing to really help when refactoring code and updating dependencies. It's nicer to get compilation errors rather than finding errors in production.
+We suggest you use TypeScript, because we find the typing helpful when refactoring code and updating dependencies. It's nicer to get compilation errors rather than finding errors in production.
 
-We've put a lot of care into making it easy to make a TypeScript CLI even if you've never written TypeScript before. We generate CLIs and plugins that use [ts-node](https://github.com/TypeStrong/ts-node) to make it fast to run the TypeScript code without a compilation step. You won't have to mess around with build configuration using oclif.
+We've put a lot of care into making it easy to create a TypeScript CLI, even if you've never written TypeScript before. We generate CLIs and plugins that use [ts-node](https://github.com/TypeStrong/ts-node), which makes it fast to run the TypeScript code without a compilation step. And you don't have to mess around with build configuration using oclif.
 
-Still, the languages today are very similar. The code you write in JavaScript will be nearly identical to what you would have in TypeScript. (Just no type definitions, of course)
+Still, the two languages are very similar today. The code you write in JavaScript will be nearly identical to what you would have in TypeScript, but with no type definitions of course. 
 
 ## What editor is best for oclif?
 
-Of course if you already have a go-to editor, you should use that. However, we typically recommend [vscode](https://code.visualstudio.com).
+If you already have a favorite editor, go ahead and keep using it. However, we typically recommend [Visual Studio Code](https://code.visualstudio.com), or VS Code for short.
 
-Microsoft has done a great job with this editor and it works particularly well in TypeScript projects. You'll get nice type checking, linting, and autocomplete right out of the box.
+Microsoft has done a great job with this editor and it works particularly well for TypeScript projects. You get nice type checking, linting, and autocomplete, right out of the box.
 
 ## Should I use npm or yarn?
 
-It really doesn't make that much of a difference. If you're just getting started, keep it simple and use npm which comes with Node. We like to use yarn internally as it's a bit faster and we find the lockfiles friendlier.
+It doesn't make that much of a difference. If you're just getting started, keep it simple and use npm, which comes with Node. We like to use yarn internally, as it's a bit faster and we find the lockfiles friendlier.
 
 ## How can I make the oclif generator run faster?
 
-If you're using npx, install it first with `npm install -g oclif`. This won't stay current with updates though, so you'll need to run `npm update -g oclif` to get new versions of the generator.
+If you're using npx, first install oclif by running `npm install -g oclif`. But to stay current with the latest updates, you must manually run `npm update -g oclif` to get new versions of the generator.
 
 ## Why isn't Node X supported?
 
-The oclif project follows and supports [Node's LTS support schedule](https://nodejs.org/en/about/releases/). This allows oclif to stay current with Node's development.
+The oclif project follows and supports [Node's LTS support schedule](https://nodejs.org/en/about/releases/), which allows oclif to stay current with Node's development.
 
 ## How do I pronounce "oclif"?
 

docs/features.md

@@ -2,60 +2,62 @@
 title: Features
 ---
 
-### Flag/Argument parsing
+Here are some key features that set oclif apart from other CLI frameworks.
 
-No CLI framework would be complete without a flag parser. We've built a custom one from years of experimentation that we feel consistently handles user input flexible enough for the user to be able to easily use the CLI in ways they expect, but without compromising strictness guarantees to the developer.
+### Flag and Argument Parsing
+
+No CLI framework is complete without a flag parser. We've built a custom flag parser from years of experimentation that we feel is flexible enough to make an easy, predictable user experience but without compromising type safety for the developer.
 
 ### Configurable Topic Separators
 
-By default topics will be separated with colons, e.g. `my:awesome:command`. However, you have the option to use spaces if you prefer, e.g. `my awesome command`.
+By default, topics are separated with colons, such as `my:awesome:command`. However, you can use spaces if you prefer, such as `my awesome command`.
 
 ### Super Speed
 
-The overhead for running an oclif CLI command is almost nothing. [It requires very few dependencies](https://www.npmjs.com/package/@oclif/core?activeTab=dependencies) (only 28 dependencies in a minimal setup—including all transitive dependencies). Also, only the command to be executed will be required with node. So large CLIs with many commands will load just as fast as a small one with a single command.
+The overhead for running an oclif CLI command is almost nothing. [The command requires few dependencies](https://www.npmjs.com/package/@oclif/core?activeTab=dependencies); for example, only 28 dependencies are required for a minimal setup, including all transitive dependencies. Also, only the command to be executed requires Node.js. Which means that a large CLI with many commands loads as fast as a small CLI with just a single command.
 
 ### CLI Generator
 
-Run a single command to scaffold out a fully functional CLI and get started quickly. See [Generator Commands](https://oclif.io/docs/generator_commands).
+You can get started from scratch quickly; all you need is a single command to scaffold out a fully functional CLI. See [Generator Commands](https://oclif.io/docs/generator_commands).
 
 ### Testing Helpers
 
-We've put a lot of work into making commands easily testable and easy to mock out stdout/stderr. The generator will automatically create scaffolded tests.
+We've worked hard to make commands easily testable and easy to mock out stdout and stderr. The CLI generator automatically creates scaffolded tests.
 
 ### Auto-documentation
 
-By default you can pass `--help` to the CLI to get help such as flag options and argument information. This information is also automatically placed in the README whenever the npm package of the CLI is published. See the [plugin-plugins](https://github.com/oclif/plugin-plugins) as an example.
+By default, you pass `--help` to a CLI command to get help, such as the flag options and argument information. This information is also automatically added to the README whenever the CLI's npm package is published. See the [plugin-plugins](https://github.com/oclif/plugin-plugins) as an example.
 
 ### Plugins
 
-Using plugins, users of the CLI can extend it with new functionality, a CLI can be split into modular components, and functionality can be shared amongst multiple CLIs. See [Building your own plugin](https://oclif.io/docs/plugins#building-your-own-plugin).
+Using plugins, you can extend a CLI with new functionality, split it into modular components, and share its functionality among multiple CLIs. See [Building your own plugin](https://oclif.io/docs/plugins#building-your-own-plugin).
 
 ### Hooks
 
-Use lifecycle hooks to run functionality any time a CLI starts, or on custom triggers. Use this whenever custom functionality needs to be shared between various components of the CLI. See [Hooks](https://oclif.io/docs/hooks).
+Use lifecycle hooks to run functionality anytime a CLI starts, or on custom triggers. Use hooks whenever you want to share custom functionality between various components of the CLI. See [Hooks](https://oclif.io/docs/hooks).
 
 ### JSON Output
 
-You can opt-in to using the `--json` flag which will automatically suppress console logs and display the final result of the command as valid JSON output. This is very useful if you want your CLI to be used for scripting in CI/CD environments. See [JSON](https://oclif.io/docs/json).
+Your CLI can opt in to using the `--json` flag, which causes commands to automatically suppress console logs and display their final results as valid JSON output. The `--json` flag is useful if you want to use your CLI for scripting in CI/CD environments. See [JSON](https://oclif.io/docs/json).
 
 ### Flexible Taxonomy
 
-You can opt-in to what we call [flexible taxonomy](./flexible_taxonomy.md). When enabled, this features allows users to execute commands without adhering to your defined command taxonomy.
+You can opt in to what we call [flexible taxonomy](./flexible_taxonomy.md). When enabled, this feature allows users to execute commands without adhering to your defined command taxonomy.
 
-This is a great way to make your CLI more user friendly, especially if you have long command names that can be hard for users to remember. For example, it might be hard for users to remember if the command is called `project deploy metadata start` or if it's called `project start deploy metadata` - with flexible taxonomy, both are valid!
+This feature makes your CLI more user-friendly, especially if you have long command names which users find difficult to remember. For example, users can find it hard to remember if a command is called `project deploy metadata start` or `project start deploy metadata` - with flexible taxonomy, it doesn't matter because both are valid!
 
 ### TypeScript (or not)
 
-Everything in the core of oclif is written in TypeScript and the generator can build fully configured TypeScript CLIs or just plain JavaScript CLIs. By virtue of static properties in TypeScript the syntax is a bit cleaner in TypeScript — but everything will work no matter which language you choose. If you use plugins support, the CLI will automatically use `ts-node` to run the plugins making it easy and fast to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
+Everything in the core of oclif is written in TypeScript, and the CLI generator can build both fully configured TypeScript or plain JavaScript CLIs. Because of TypeScript static properties, the syntax is a bit cleaner in TypeScript — but everything works, no matter which language you choose. If you use plugins support, the CLI automatically uses `ts-node` to run the plugins, which makes it easy and fast to use TypeScript with minimal-to-no boilerplate needed for any oclif CLI.
 
-### Auto-updating Installers
+### Auto-Updating Installers
 
-oclif can package your CLI into [different installers](releasing.md) that will not require the user to already have node installed on the machine. These can be made auto-updatable by using [plugin-update](https://github.com/oclif/plugin-update).
+oclif can package your CLI into [different installers](releasing.md) that don't require the user to already have Node.js installed on their computer. You can make these installers auto-updatable by using [plugin-update](https://github.com/oclif/plugin-update).
 
 ### Autocomplete
 
-Include terminal autocompletion for your CLI via [plugin-autocomplete](https://github.com/oclif/plugin-autocomplete). Once installed, users can complete command names and flag names.
+Include terminal autocompletion for your CLI with the [plugin-autocomplete](https://github.com/oclif/plugin-autocomplete). After the autocomplete feature is configured, users can complete command names and flag names by pressing the <TAB> key. 
 
 ```bash
-$ my-cli p<tab><tab> # will list all commands starting with 'p' for completion
+$ my-cli p<tab><tab> # lists all commands starting with 'p' for completion
 ```

docs/generator_commands.md

@@ -2,13 +2,17 @@
 title: Generator Commands
 ---
 
+Use these commands to generate the scaffoling for a new CLI, a command, or a hook. The scaffolding includes CLI configuration files, scripts, and sample TypeScript files for a simple  `hello world` command. 
+
+Run each command with the `--help` flag, but without its argument, to see the same information documented below; for example, `oclif generate --help`. 
+
 - [`oclif generate NAME`](#oclif-generate-name)
 - [`oclif generate command NAME`](#oclif-generate-command-name)
 - [`oclif generate hook NAME`](#oclif-generate-hook-name)
 
 ## `oclif generate NAME`
 
-Generate a new CLI
+Generate a new CLI. 
 
 ```
 USAGE