docs: update links, copy edit, apply style guide (#2294)

Co-authored-by: Luke Russell <[email protected]>
Co-authored-by: Eden Zimbelman <[email protected]>

Author: 3 people

.github/contributing.md

@@ -24,9 +24,9 @@ There are many ways you can contribute! :heart:
 
 ### Tests :mag:, Documentation :books:, Miscellaneous :sparkles:
 -  If you'd like to improve the tests, you want to make the documentation clearer, you have an
-   alternative implementation of something that may have advantages over the way its currently
+   alternative implementation of something that may have advantages over the way it's currently
    done, or you have any other change, we would be happy to hear about it!
-  -  If its a trivial change, go ahead and [send a Pull Request](#creating_a_pull_request) with the changes you have in mind.
+  -  If it's a trivial change, go ahead and [send a Pull Request](#creating_a_pull_request) with the changes you have in mind.
   -  If not, [open an Issue](https://github.com/slackapi/node-slack-sdk/issues/new) to discuss the idea first.
 
 If you're new to our project and looking for some way to make your first contribution, look for

.github/maintainers_guide.md

@@ -159,7 +159,7 @@ Releasing can feel intimidating at first, but rest assured: if you make a mistak
 ### 🔖 Versioning and Tags
 This project is versioned using [Semantic Versioning](http://semver.org/), particularly in the [npm flavor](https://docs.npmjs.com/getting-started/semantic-versioning). Each release is tagged using git. The naming convention for tags is `{package_name}@{version}`. For example, the tag `@slack/[email protected]` marks the v5.0.0 release of the `@slack/web-api` package. A single commit will have multiple tags when multiple packages are released simultaneously.
 
-One package that expands upon the standard major.minor.patch version schema typically associated with Semantic Versioning is the `@slack/cli-test` package. This package employs standard major.minor.patch version, in addition to a [build metadata suffix](https://semver.org/#spec-item-10) suffix of the form `+cli.X.Y.Z`, e.g. `0.1.0+cli.2.24.0`. The version after `+cli.` communicates compatibility between the `@slack/cli-test` package and the [Slack Platfrom CLI](https://api.slack.com/automation/quickstart) itself.
+One package that expands upon the standard major.minor.patch version schema typically associated with Semantic Versioning is the `@slack/cli-test` package. This package employs standard major.minor.patch version, in addition to a [build metadata suffix](https://semver.org/#spec-item-10) suffix of the form `+cli.X.Y.Z`, e.g. `0.1.0+cli.2.24.0`. The version after `+cli.` communicates compatibility between the `@slack/cli-test` package and the [Slack Platfrom CLI](https://tools.slack.dev/slack-cli/) itself.
 
 ### 🪵 Branches
 `main` is where active development occurs. Long running named feature branches are occasionally created for collaboration on a feature that has a large scope (because everyone cannot push commits to another person's open Pull Request). After a major version increment, a maintenance branch for the older major version is left open (e.g. `v3`, `v4`, etc).

README.md

@@ -19,10 +19,10 @@ Slack's APIs. They are small and powerful when used independently, and work seam
 **Just starting out?** The [Getting Started tutorial](https://slackapi.github.io/node-slack-sdk/getting-started) will
 walk you through building your first Slack app using Node.js.
 
-| Slack API    | What its for | NPM Package      |
+| Slack API    | Use | NPM Package      |
 |--------------|--------------|-------------------|
-| Web API      | Send data to or query data from Slack using any of [over 220 methods](https://api.slack.com/methods). | [`@slack/web-api`](https://tools.slack.dev/node-slack-sdk/web-api) |
-| OAuth        | Setup the authentication flow using V2 OAuth for Slack apps as well as V1 OAuth for classic Slack apps. | [`@slack/oauth`](https://tools.slack.dev/node-slack-sdk/oauth) |
+| Web API      | Send data to or query data from Slack using any of [over 220 methods](https://docs.slack.dev/reference/methods). | [`@slack/web-api`](https://tools.slack.dev/node-slack-sdk/web-api) |
+| OAuth        | Set up the authentication flow using V2 OAuth for Slack apps as well as V1 OAuth for classic Slack apps. | [`@slack/oauth`](https://tools.slack.dev/node-slack-sdk/oauth) |
 | Incoming Webhooks | Send notifications to a single channel which the user picks on installation. | [`@slack/webhook`](https://tools.slack.dev/node-slack-sdk/webhook) |
 | Socket Mode  | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | [`@slack/socket-mode`](https://tools.slack.dev/node-slack-sdk/socket-mode) |
 
@@ -58,7 +58,7 @@ package's documentation, linked in the table above.
 Your app will interact with the Web API through the `WebClient` object, which is an export from `@slack/web-api`. You
 typically instantiate a client with a token you received from Slack. The example below shows how to post a message into
 a channel, DM, MPDM, or group. The `WebClient` object makes it simple to call any of the [**over 130 Web API
-methods**](https://api.slack.com/methods).
+methods**](https://docs.slack.dev/reference/methods).
 
 ```javascript
 const { WebClient } = require('@slack/web-api');
@@ -72,7 +72,7 @@ const web = new WebClient(token);
 const conversationId = 'C1232456';
 
 (async () => {
-  // See: https://api.slack.com/methods/chat.postMessage
+  // See: https://docs.slack.dev/reference/methods/chat.postMessage
   const res = await web.chat.postMessage({ channel: conversationId, text: 'Hello there' });
 
   // `res` contains information about the posted message

docs/content/getting-started.md

@@ -2,38 +2,27 @@
 title: Getting Started
 ---
 
-This tutorial will show you how to use the packages in this Node Slack SDK to get a simple Slack app running. If you've
+This guide shows how to use the packages in the Node Slack SDK to get a simple Slack app running. If you've
 never used the Slack APIs before, you're in the right place. Welcome, and let's get started!
 
 ## Create a Slack app
 
-The first step is to [create a new app](https://api.slack.com/apps?new_granular_bot_app=1) with Slack at the API website. Give your app a
-fun name and choose a Development Slack Workspace. We recommend using a workspace where you aren't going to disrupt real
-work getting done — you can create a new one for free. After you create an app, you'll be greeted with some basic information.
+The first step is to [create a new app](https://api.slack.com/apps?new_app=1). Give your app a fun name and choose a development Slack workspace. We recommend using a workspace where you aren't going to disrupt real work getting done — you can create a new one for free. After you create an app, you'll be greeted with some basic information.
 
-In this guide we'll be **calling a method of Web API** to post a message to a channel. The Web API is the foundation of
-the Slack Platform, and almost every Slack app uses it. Aside from posting messages, the Web API allows your app to call
-[methods](https://api.slack.com/methods) that can be used for everything from creating a channel to updating a user's
-status. Before we can call any methods, we need to configure our new app with the proper permissions.
+In this guide, we'll be calling a method of the Web API to post a message to a channel. The Web API is the foundation of
+the Slack platform, and nearly every Slack app uses it. Aside from posting messages, the Web API allows your app to call
+[methods](https://docs.slack.dev/reference/methods) that can be used for everything from creating a channel to updating a user's status. Before we can call any methods, we first need to configure our new app with the proper permissions.
 
 ## Get a token to use the Web API
 
-Navigate to **OAuth & Permissions** and scroll down to the section for scopes. Slack describes the various permissions
-your app could obtain from an installing bot as **scopes**. There are [over 80 scopes](https://api.slack.com/scopes)!
-Some are broad and authorize your app to access lots of data, while others are very specific and let your app touch just
-a tiny sliver. Your users (and their IT admins) will have opinions about which data your app should access, and only
-agree to install the app if the data permissions seem reasonable, so we recommend finding the scope(s) with the least
-amount of privilege for your app's needs. In this guide we will use the Web API to post a message. The scope required
-for this is called [`chat:write`](https://api.slack.com/scopes/chat:write). Scroll down to "Bot Token Scopes", ensure this section is expanded, then click "Add an OAuth Scope", find the
-[`chat:write`](https://api.slack.com/scopes/chat:write) scope and select it to add it to your app.
+In your [app settings](https://api.slack.com/apps), select the app you created and navigate to **OAuth & Permissions** in the left nav. Scroll down to the section for scopes. Slack describes the various permissions
+your app could obtain from an installing bot as scopes. There are [over 80 scopes](https://docs.slack.dev/reference/scopes)! Some are broad and authorize your app to access lots of data, while others are very specific and let your app touch just a tiny sliver. Your users (and their IT admins) will have opinions about which data your app should access and only agree to install the app if the data permissions seem reasonable, so we recommend finding the scope(s) with the least amount of privilege for your app's needs. In this guide, we will use the Web API to post a message. The scope required for this is [`chat:write`](https://docs.slack.dev/reference/scopes/chat.write). Scroll down to **Bot Token Scopes**, ensure this section is expanded, then click **Add an OAuth Scope**, find the [`chat:write`](https://docs.slack.dev/reference/scopes/chat.writee) scope and select it to add it to your app.
 
-Now our app has described which scope it desires in the workspace, but we haven't added it to your workspace yet. To install your app, scroll up to the top of the page and click the **Install to Workspace** button. You'll be taken to the app installation page. This page is where you grant the bot user permission to install the app in your development workspace with specific capabilities.
+Now our app has declared which scope it desires in the workspace, but we haven't added it to your workspace yet. To install your app, scroll up to the top of the page and click the **Install to Workspace** button. You'll be taken to the app installation page. This page is where you grant the bot user permission to install the app in your development workspace with specific capabilities.
 
-Go ahead and click "Allow". This will install the app on the workspace and generate the token we'll need.
+Click **Allow**. This will install the app on the workspace and generate the token we'll need.
 
-When you return to the **OAuth & Permissions** page copy the **Bot User OAuth Access Token** (it should begin with `xoxb`). Treat
-this value like a password and keep it safe. The Web API uses tokens to authenticate the requests your app makes. In
-a later step, you'll be asked to use this token in your code.
+When you return to the **OAuth & Permissions** page, copy the **Bot User OAuth Access Token** (it should begin with `xoxb`). Treat this value like a password and keep it safe. The Web API uses tokens to authenticate the requests your app makes. In a later step, you'll be asked to use this token in your code.
 
 ## Set up your local project
 
@@ -72,15 +61,15 @@ If you see the same output as above, we're ready to start.
 
 ## Send a message with the Web API
 
-In this guide we'll post a simple message that contains the current time. We'll also follow the best practice of keeping
+In this guide, we'll post a simple message that contains the current time. We'll also follow the best practice of keeping
 secrets outside of your code (do not hardcode sensitive data).
 
 Before we move forward, add the bot user you created above to the `#general` channel in your workspace. Bots need to be
 invited to channels to be able to post in them. You can do this by going to the `#general` channel inside slack in your workspace and
 type `/invite @YourBotUser` with the display name of your bot user.
 
 Store the access token in a new environment variable. The following example works on Linux and MacOS; but [similar
-commands are available on Windows](https://superuser.com/a/212153/94970). Replace the value with OAuth Access Token that
+commands are available on Windows](https://superuser.com/a/212153/94970). Replace the value with OAuth Access token that
 you copied earlier.
 
 ```shell
@@ -132,9 +121,8 @@ You just built your first Slack app with Node.js! 🎉
 There's plenty more to learn and explore about the Node Slack SDK and the Slack platform. Here are some ideas about where to look next:
 
 * This tutorial only used two of **over 200 Web API methods** available. [Look through
-  them](https://api.slack.com/methods) to get ideas about what to build next!
+  them](https://docs.slack.dev/reference/methods) to get ideas about what to build next!
 
 * You now know how to build a Slack app for a single workspace, [learn how to implement Slack
-OAuth](https://api.slack.com/authentication/oauth-v2) to make your app installable in many workspaces. If you are using
-  [Passport](http://www.passportjs.org/) to handle authentication, you may find the
+OAuth](https://docs.slack.dev/authentication/installing-with-oauth) to make your app installable in many workspaces. If you are using [Passport](http://www.passportjs.org/) to handle authentication, you may find the
   [`@aoberoi/passport-slack`](https://github.com/aoberoi/passport-slack) strategy package helpful.

docs/content/index.md

@@ -3,7 +3,7 @@ title: Node Slack SDK
 slug: /
 ---
 
-The Node Slack SDK is a collection of single-purpose packages aimed at making building Slack apps performant, secure, and scalable. 
+The Node Slack SDK is a collection of single-purpose packages for building Slack apps that are performant, secure, and scalable. 
 
 **Just starting out?** The [Getting Started tutorial](/getting-started) will walk you through building your first Slack app using Node.js.
 
@@ -13,16 +13,16 @@ The Node Slack SDK has corresponding packages for Slack APIs. They are small and
 
 | Slack API    | Use | NPM package      |
 |--------------|--------------|-------------------|
-| Web API      | Send data to or query data from Slack using any of [over 200 methods](https://api.slack.com/methods). | [`@slack/web-api`](/web-api) |
-| OAuth        | Set up the authentication flow using V2 OAuth for Slack apps as well as V1 OAuth for classic Slack apps. | [`@slack/oauth`](/oauth) |
-| Incoming Webhooks | Send notifications to a single channel which the user picks on installation. | [`@slack/webhook`](/webhook) |
+| Web API      | Send data to or query data from Slack using any of [more than 200 methods](https://docs.slack.dev/reference/methods). | [`@slack/web-api`](/web-api) |
+| OAuth        | Set up the authentication flow using V2 OAuth for Slack apps. | [`@slack/oauth`](/oauth) |
+| Incoming Webhooks | Send notifications to a single channel that the user picks on installation. | [`@slack/webhook`](/webhook) |
 | Socket Mode  | Listen for incoming messages and a limited set of events happening in Slack, using WebSocket. | [`@slack/socket-mode`](/socket-mode) |
 
 :::warning[Deprecation Notice]
 
 `@slack/events-api` and `@slack/interactive-messages` officially reached EOL on May 31st, 2021. Development has fully stopped for these packages and all remaining open issues and pull requests have been closed.
 
-At this time, we recommend migrating to [Bolt for JavaScript](https://github.com/slackapi/bolt-js), a framework that offers all of the functionality available in those packages (and more). To help with that process, we've provided some [migration samples](/tutorials/migrating-to-v6) for those looking to convert their existing apps.
+At this time, we recommend migrating to [Bolt for JavaScript](https://tools.slack.dev/bolt-js), a framework that offers all of the functionality available in those packages (and more).
 
 :::
 

docs/content/migration/migrating-socket-mode-package-to-v2.md

@@ -11,8 +11,8 @@ npm i @slack/socket-mode
 ## Breaking Changes
 
 1. Two [Lifecycle Events](https://github.com/slackapi/node-slack-sdk/tree/main/packages/socket-mode#lifecycle-events) have been removed: 
-  - `authenticated`. This event corresponded to the client retrieving a response from the [`apps.connections.open`](https://api.slack.com/methods/apps.connections.open) Slack API method - but it didn't signal anything about the actual socket connection that matters! If you had been listening to this event, we recommend moving instead to one of these two events:
+  - `authenticated`. This event corresponded to the client retrieving a response from the [`apps.connections.open`](https://docs.slack.dev/reference/methods/apps.connections.open) Slack API method - but it didn't signal anything about the actual socket connection that matters! If you had been listening to this event, we recommend moving instead to one of these two events:
     - `connected`. This signals that the client has established a connection with Slack and has received a `hello` message from the Slack backend. Events will start flowing to your app after this event.
     - `connecting`. This signals that the client is about to establish a connection with Slack. If you were using `authenticated` to be notified _before_ the client establishes a connection, we recommend using this event instead.
-  - `unable_to_socket_mode_start`. This event corresponded to an error happening when attempting to hit the [`apps.connections.open`](https://api.slack.com/methods/apps.connections.open) Slack API method. We recommend moving instead to `reconnecting` (if you have client reconnections enabled), or the `error` event.
+  - `unable_to_socket_mode_start`. This event corresponded to an error happening when attempting to hit the [`apps.connections.open`](https://docs.slack.dev/reference/methods/apps.connections.open) Slack API method. We recommend moving instead to `reconnecting` (if you have client reconnections enabled), or the `error` event.
 2. Two public properties on the client have been removed: `connected` and `authenticated`. Instead, we recommend migrating to the `isActive()` method to determine whether the WebSocket connection powering the client is healthy.