Merge pull request slackapi#193 from shanedewael/misc-docs-fixes

Miscellaneous docs improvements

docs/_advanced/authorization.md

@@ -7,13 +7,13 @@ order: 2
 <div class="section-content">
 Authorization is the process of deciding which Slack credentials (such as a bot token) should be available while processing a specific incoming event.
 
-Custom apps installed on a single workspace can simply use the `token` option at the time of `App` initialization. However, when your app needs to handle multiple tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the `authorize` option should be used instead.
+Custom apps installed on a single workspace can simply use the `token` option at the time of `App` initialization. However, when your app needs to handle several tokens, such as cases where it will be installed on multiple workspaces or needs access to more than one user token, the `authorize` option should be used instead.
 
-The `authorize` option should be set to a function that takes an event source as its input, and should return a Promise for an object containing the authorized credentials. The source contains information about who and where the event is coming from using properties like `teamId` (always available), `userId`, `conversationId`, and `enterpriseId`.
+The `authorize` option can be set to a function that takes an event source as its input, and should return a Promise for an object containing the authorized credentials. The source contains information about who and where the event is coming from by using properties like `teamId` (always available), `userId`, `conversationId`, and `enterpriseId`.
 
-The authorized credentials should also have a few specific properties: `botToken`, `userToken`, `botId` (required for app to ignore messages from itself), and `botUserId`. You can also include any other properties you'd like to make available on the [`context`](#context).
+The authorized credentials should also have a few specific properties: `botToken`, `userToken`, `botId` (required for an app to ignore messages from itself), and `botUserId`. You can also include any other properties you'd like to make available on the [`context`](#context) object.
 
-You should always provide either one or both of the `botToken` and `userToken` properties. One of them is necessary to make helpers like `say()` work. If they are both given, then `botToken` will take precedence.
+You should always provide either one or both of the `botToken` and `userToken` properties. At least one of them is necessary to make helpers like `say()` work. If they are both given, then `botToken` will take precedence.
 </div>
 
 ```javascript

docs/_advanced/conversation_store.md

@@ -6,12 +6,12 @@ order: 3
 
 <div class="section-content">
 Bolt includes support for a store, which sets and retrieves state related to a conversation. Conversation stores have two methods:
-* `set()` modifies conversation state. `set()` requires a `conversationId` of type string, `value` that can be any type, and an optional `expiresAt` of type number.  `set()` returns a `Promise`.
-* `get()` fetches conversation state from the store. Get requires a `conversationId` of type string and returns a Promise with the conversation’s state.
+* `set()` modifies conversation state. `set()` requires a `conversationId` of type string, `value` of any type, and an optional `expiresAt` of type number. `set()` returns a `Promise`.
+* `get()` fetches conversation state from the store. `get()` requires a `conversationId` of type string and returns a Promise with the conversation’s state.
 
-`conversationContext()` is a built-in [global middleware](#global-middleware) that allows conversations to be updated by middleware. When receiving an event, middleware functions can use `context.updateConversation()` to set state and reading from `context.conversation` to retrieve it.
+`conversationContext()` is a built-in [global middleware](#global-middleware) that allows conversations to be updated by other middleware. When receiving an event, middleware functions can use `context.updateConversation()` to set state and `context.conversation` to retrieve it.
 
-The default (built-in) conversation store simply stores conversation state in memory. While this is sufficient for some situations, if there is more than one instance of your app running the state will not be shared among your processes so you’ll want to implement a conversation store that fetches conversation state from a database.
+The built-in conversation store simply stores conversation state in memory. While this is sufficient for some situations, if there is more than one instance of your app running, the state will not be shared among the processes so you’ll want to implement a conversation store that fetches conversation state from a database.
 </div>
 
 ```javascript

docs/_advanced/error_handling.md

@@ -5,7 +5,7 @@ order: 1
 ---
 
 <div class="section-content">
-If an error occurs in a listener, it’s recommended you handle it directly. However, there are cases where errors may occur after your listener middleware has returned (such as `say()`, `respond()`, or not calling `ack()`). By default, these errors will be logged to the console. To handle them yourself, you can attach a global error handler to your app using the `error(fn)` method.
+If an error occurs in a listener, it’s recommended you handle it directly. However, there are cases where errors may be triggered after your listener has already returned (such as in `say()`, `respond()`, or if you don't call `ack()` when it's required). By default, these errors will be logged to the console. To handle them yourself, you can attach a global error handler to your app with the `error(fn)` method.
 
 If you want more control over errors, it’s advised to use the [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) method attached to your app under the `client` key (instead of `say()` or `respond()`). This returns a `Promise` that can be caught to handle the error.
 </div>

docs/_advanced/logging.md

@@ -26,7 +26,7 @@ const app = new App({
 </summary>
 
 <div class="secondary-content" markdown="0">
-If you want to send logs to somewhere besides the console or want more control over the logger, you can implement a logger. A custom logger must implement specific methods (known as the `Logger` interface):
+If you want to send logs to somewhere besides the console or want more control over the logger, you can implement a custom logger. A custom logger must implement specific methods (known as the `Logger` interface):
 
 | Method       | Parameters        | Return type |
 |--------------|-------------------|-------------|

docs/_advanced/middleware_global.md

@@ -7,7 +7,7 @@ order: 4
 <div class="section-content">
 Global middleware is run for all incoming events before any listener middleware. You can add any number of global middleware to your app by utilizing `app.use(fn(payload,...,next))`. 
 
-Both global and listener middleware must call `next()` to pass control of the execution chain to the next middleware, or call `next(error)` to pass an error back up the already-executed middleware chain.
+Both global and listener middleware must call `next()` to pass control of the execution chain to the next middleware, or call `next(error)` to pass an error back up the previously-executed middleware chain.
 
 As an example, let's say your app should only respond to users identified with a corresponding internal authentication service (an SSO provider or LDAP, for example). You may define a global middleware that looks up a user record in the authentication service and errors if the user is not found.
 </div>

docs/_advanced/middleware_listener.md

@@ -9,7 +9,7 @@ Listener middleware is used for logic across many listener functions (but usuall
 
 There’s a collection of built-in listener middleware that you can use like `subtype()` for filtering on a message subtype and `directionMention()` which filters out any message that doesn’t directly @-mention your bot. 
 
-But of course, you can write your own middleware for more custom functionality. While writing your own middleware, your function must call `next()` to pass control to the next middleware, or calling `next(error)` to pass an error back up the already-executed middleware chain.
+But of course, you can write your own middleware for more custom functionality. While writing your own middleware, your function must call `next()` to pass control to the next middleware, or call `next(error)` to pass an error back up the previously-executed middleware chain.
 
 As an example, let’s say your listener should only deal with messages from humans. You can write a listener middleware that excludes any bot messages.
 

docs/_advanced/receiver.md

@@ -5,7 +5,7 @@ order: 8
 ---
 
 <div class="section-content">
-A receiver is responsible for handling and parsing any incoming requests from Slack, then emitting the request so the Bolt app can add context and pass the request to your app’s listeners. Receivers must conform to the Receiver interface:
+A receiver is responsible for handling and parsing any incoming events from Slack, then emitting the event so the Bolt app can add context and pass it to your app’s listeners. Receivers must conform to the Receiver interface:
 
 | Method       | Parameters                       | Return type |
 |--------------|----------------------------------|-------------|
@@ -17,7 +17,7 @@ A receiver is responsible for handling and parsing any incoming requests from Sl
 * `Receiver.on('message',  listener)` should route all incoming requests that have been parsed to `onIncomingEvent()`. It’s called in the Bolt app as `this.receiver.on('message', message => this.onIncomingEvent(message))`.
 * `Receiver.on('error',  listener)` should route errors to the global error handler. It’s called in the Bolt app as `this.receiver.on('error', error => this.onGlobalError(error))`.
 
-To use a custom receiver, you’ll need to pass it into the constructor when initializing your Bolt app. Here is what a basic custom receiver might look like.
+To use a custom receiver, you can pass it into the constructor when initializing your Bolt app. Here is what a basic custom receiver might look like.
 
 For a more in-depth look at a receiver, [read the source code for the built-in Express receiver](https://github.com/slackapi/bolt/blob/master/src/ExpressReceiver.ts)
 </div>

docs/_basic/listening_actions.md

@@ -7,9 +7,9 @@ order: 5
 <div class="section-content">
 Your app can listen to user actions like button clicks, menu selects, and message actions using the `action` method.
 
-Actions can be filtered on  an `action_id` of type string or RegExp. `action_id`s act as unique identifiers for interactive components on the Slack platform. 
+Actions can be filtered on an `action_id` of type string or RegExp object. `action_id`s act as unique identifiers for interactive components on the Slack platform. 
 
-You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge the event was received from Slack. This is discussed in the [acknowledging requests section](#acknowledge).
+You’ll notice in all `action()` examples, `ack()` is used. It is required to call the `ack()` function within an action listener to acknowledge that the event was received from Slack. This is discussed in the [acknowledging events section](#acknowledge).
 
 </div>
 
@@ -27,7 +27,7 @@ app.action('approve_button', async ({ ack, say }) => {
 </summary>
 
 <div class="secondary-content" markdown="0">
-You can use a constraints object to listen to `callback_id`s, `block_id`s, and `action_id`s (or any combination of them). Constraints in the object can be of type string or RegExp.
+You can use a constraints object to listen to `callback_id`s, `block_id`s, and `action_id`s (or any combination of them). Constraints in the object can be of type string or RegExp object.
 </div>
 
 ```javascript

docs/_basic/listening_events.md

@@ -5,7 +5,7 @@ order: 3
 ---
 
 <div class="section-content">
-You can listen to [any Events API event](https://api.slack.com/events) using the `event()` method by subscribing to it in your app configuration. on your This allows your app to take action when something happens in Slack, like a user reacting to a message or joining a channel.
+You can listen to [any Events API event](https://api.slack.com/events) using the `event()` method after subscribing to it in your app configuration. This allows your app to take action when something happens in Slack, like a user reacting to a message or joining a channel.
 
 The `event()` method requires an `eventType` of type string.
 </div>

docs/_basic/listening_messages.md

@@ -5,9 +5,9 @@ order: 1
 ---
 
 <div class="section-content">
-To listen to messages that [your app has access to receive](https://api.slack.com/messaging/retrieving#permissions), you can use the `message()` method. This method filters out any events that aren’t of type `message`.
+To listen to messages that [your app has access to receive](https://api.slack.com/messaging/retrieving#permissions), you can use the `message()` method which filters out events that aren’t of type `message`.
 
-It accepts an optional `pattern` parameter of type `string` or `RegExp` object that will filter out any messages that don’t match.
+`message()` accepts an optional `pattern` parameter of type `string` or `RegExp` object which filters out any messages that don’t match the pattern.
 </div>
 
 ```javascript

docs/_basic/listening_responding_commands.md

@@ -5,7 +5,7 @@ order: 8
 ---
 
 <div class="section-content">
-Your app can use the `command()` method to listen to incoming slash command payloads. The method requires a `commandName` of type string.
+Your app can use the `command()` method to listen to incoming slash command events. The method requires a `commandName` of type string.
 
 Commands must be acknowledged with `ack()` to inform Slack your app has received the event.
 

docs/_basic/responding_actions.md

@@ -5,7 +5,7 @@ order: 6
 ---
 
 <div class="section-content">
-There are two main ways to respond to actions. The first way (and the most common way) is using the `say` function. The `say` function sends a message back to the conversation where the incoming event took place.
+There are two main ways to respond to actions. The first (and most common) way is to use the `say` function. The `say` function sends a message back to the conversation where the incoming event took place.
 
 The second way to respond to actions is using `respond()`, which is a simple utility to use the `response_url` associated with an action.
 </div>
@@ -25,7 +25,7 @@ app.action('approve_button', ({ ack, say }) => {
 </summary>
 
 <div class="secondary-content" markdown="0">
-Since `respond()` is a utility for calling the `response_url`, it behaves in the same way. You can pass a JSON object with a new message payload that will be published back to the source of the original interaction with optional properties like `response_type` (`in_channel` or `ephemeral`), `replace_original`, and `delete_original`.
+Since `respond()` is a utility for calling the `response_url`, it behaves in the same way. You can pass a JSON object with a new message payload that will be published back to the source of the original interaction with optional properties like `response_type` (which has a value of `in_channel` or `ephemeral`), `replace_original`, and `delete_original`.
 </div>
 
 ```javascript

docs/_basic/sending_messages.md

@@ -5,7 +5,7 @@ order: 2
 ---
 
 <div class="section-content">
-Within your listener function, `say()` is available whenever there is an associated conversation (for example, the conversation where the event or action which triggered the listener occurred). `say()` accepts a string to post simple text-based messages and JSON payloads to send more complex messages. The message payload you pass in will be sent to the associated conversation.
+Within your listener function, `say()` is available whenever there is an associated conversation (for example, a conversation where the event or action which triggered the listener occurred). `say()` accepts a string to post simple messages and JSON payloads to send more complex messages. The message payload you pass in will be sent to the associated conversation.
 
 In the case that you'd like to send a message outside of a listener or you want to do something more advanced (like handle specific errors), you can call `chat.postMessage` [using the client attached to your Bolt instance](#web-api).
 </div>