docs: guide the great documentation reader down a clear path

Co-authored-by: Fil Maj <[email protected]>

README.md

@@ -125,19 +125,19 @@ in JSON or YAML format:
 
 ### Technique 2: Slack API method
 
-A bot token or user token or [token of some other kind][tokens] can be used to
+A bot token or user token or [token of some other kind][tokens] must be used to
 call one of [the Slack API methods][methods] with this technique.
 
 #### Setup
 
-The exact Slack API [method][methods] used will require setting various sets of
+Different Slack API [methods][methods] require different
 [scopes][scopes], but setup should be similar for all methods:
 
 1. [Create a Slack app][apps] for your workspace or use an existing app.
-2. Select a [method][methods] to call and add the required **scopes** to your
+2. Depending on the [method][methods] you wish to call, add the required **scopes** to your
    app under the **OAuth & Permissions** page on app settings.
 3. Install the app to your workspace using the **Install App** page.
-4. Find the [token][tokens] minted for the Slack API method being called from
+4. Once your app is installed to a workspace, a new [token][tokens] with your app's specified scopes will be minted for that workspace. It is worth noting that tokens are only valid for a single workspace! Find the token on
    the **OAuth & Permissions** page.
 5. Add the token as [a repository secret][repo-secret] called `SLACK_BOT_TOKEN`
    or something similar and memorable.
@@ -444,7 +444,7 @@ in following steps of a GitHub workflow.
 
 The following outputs are returned with each of the techniques:
 
-- `time`: `number`. The Unix [epoch time][epoch] that the job completed.
+- `time`: `number`. The Unix [epoch time][epoch] that the step completed.
 - `ok`: `boolean`. If the request completed with success.
 - `response`: `string`. The [response][response] from the request as stringified
   JSON.

src/client.js

@@ -7,7 +7,7 @@ import SlackError from "./errors.js";
  * The Client class creates a WebClient from @slack/web-api for use when calling
  * various Slack API methods.
  *
- * @see {@link https://slack.dev/node-slack-sdk/web-api/}
+ * @see {@link https://tools.slack.dev/node-slack-sdk/web-api/}
  * @see {@link https://api.slack.com/methods/}
  */
 export default class Client {