docs: npm team revamp

- Added more examples
- Removed references to removed `npm team edit` subcommand
- Grammar and spell check

PR-URL: https://github.com/npm/cli/pull/2557
Credit: @ruyadorno
Close: #2557
Reviewed-by: @wraithgar, @nlf

1 files changed, 56 insertions, 12 deletions

diff --git a/docs/content/commands/npm-team.md b/docs/content/commands/npm-team.md
index 4901ae168..96aacd8ae 100644
--- a/docs/content/commands/npm-team.md
+++ b/docs/content/commands/npm-team.md
@@ -14,8 +14,6 @@ npm team add <scope:team> <user>
 npm team rm <scope:team> <user>
 
 npm team ls <scope>|<scope:team>
-
-npm team edit <scope:team>
 ```
 
 ### Description
@@ -24,31 +22,76 @@ Used to manage teams in organizations, and change team memberships. Does not
 handle permissions for packages.
 
 Teams must always be fully qualified with the organization/scope they belong to
-when operating on them, separated by a colon (`:`). That is, if you have a `wombats` team in a `wisdom` organization, you must always refer to that team as `wisdom:wombats` in these commands.
+when operating on them, separated by a colon (`:`). That is, if you have a
+`newteam` team in an `org` organization, you must always refer to that team
+as `@org:newteam` in these commands.
 
-If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`. If you don't include this then you will be prompted.
+If you have two-factor authentication enabled in `auth-and-writes` mode, then
+you can provide a code from your authenticator with `[--otp <otpcode>]`.
+If you don't include this then you will be prompted.
 
 * create / destroy:
-  Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
-* add / rm:
-  Add a user to an existing team, or remove a user from a team they belong to.
+  Create a new team, or destroy an existing one. Note: You cannot remove the
+  `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
+
+  Here's how to create a new team `newteam` under the `org` org:
+
+  ```bash
+  npm team create @org:newteam
+  ```
+
+  You should see a confirming message such as: `+@org:newteam` once the new
+  team has been created.
+
+* add:
+  Add a user to an existing team.
+
+  Adding a new user `username` to a team named `newteam` under the `org` org:
+
+  ```bash
+  npm team add @org:newteam username
+  ```
+
+  On success, you should see a message: `username added to @org:newteam`
+
+* rm:
+  Using `npm team rm` you can also remove users from a team they belong to.
+
+  Here's an example removing user `username` from `newteam` team
+  in `org` organization:
+
+  ```bash
+  npm team rm @org:newteam username
+  ```
+
+  Once the user is removed a confirmation message is displayed:
+  `username removed from @org:newteam`
 
 * ls:
   If performed on an organization name, will return a list of existing teams
   under that organization. If performed on a team, it will instead return a list
   of all users belonging to that particular team.
 
-* edit:
-  Edit a current team.
+  Here's an example of how to list all teams from an org named `org`:
+
+  ```bash
+  npm team ls @org
+  ```
+
+  Example listing all members of a team named `newteam`:
+
+  ```bash
+  npm team ls @org:newteam
+  ```
 
 ### Details
 
 `npm team` always operates directly on the current registry, configurable from
 the command line using `--registry=<registry url>`.
 
-In order to create teams and manage team membership, you must be a *team admin*
-under the given organization. Listing teams and team memberships may be done by
-any member of the organizations.
+You must be a *team admin* to create teams and manage team membership, under
+the given organization. Listing teams and team memberships may be done by
+any member of the organization.
 
 Organization creation and management of team admins and *organization* members
 is done through the website, not the npm CLI.
@@ -59,4 +102,5 @@ use the `npm access` command to grant or revoke the appropriate permissions.
 ### See Also
 
 * [npm access](/commands/npm-access)
+* [npm config](/commands/npm-config)
 * [npm registry](/using-npm/registry)