docs: update quickstart, installation, guides, and hook reference files (#504)

* woo

* go

* go

Author: lukegalbraithrussell

docs/_sidebar.json

@@ -14,12 +14,10 @@
             "tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux",
             "tools/slack-cli/guides/installing-the-slack-cli-for-windows",
             "tools/slack-cli/guides/authorizing-the-slack-cli",
-            "tools/slack-cli/guides/using-slack-cli-with-bolt-frameworks",
             "tools/slack-cli/guides/using-slack-cli-on-an-enterprise-grid-organization",
             "tools/slack-cli/guides/running-slack-cli-commands",
             "tools/slack-cli/guides/developing-locally",
             "tools/slack-cli/guides/using-environment-variables-with-the-slack-cli",
-            "tools/slack-cli/guides/troubleshooting-slack-cli-errors",
             "tools/slack-cli/guides/setting-up-ci-cd-with-the-slack-cli",
             "tools/slack-cli/guides/deploying-with-the-slack-cli-and-github-actions",
             "tools/slack-cli/guides/removing-an-app",
@@ -54,7 +52,7 @@
             },
             {
                 "type": "doc",
-                "id": "tools/slack-cli/reference/hooks/index",
+                "id": "tools/slack-cli/reference/hooks",
                 "label": "Hooks"
             }
         ]

docs/guides/authorizing-the-slack-cli.md

@@ -55,7 +55,7 @@ Authorization Level: Workspace
 
 You should see an entry for the workspace you just authorized. If you don't, get a new authorization ticket with `slack login` to try again.
 
-You're now ready to begin building [Bolt](/tools/slack-cli/guides/using-slack-cli-with-bolt-frameworks) and [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started) apps!
+You're now ready to begin developing [Bolt](/quickstart) and [Deno Slack SDK](/tools/deno-slack-sdk/guides/getting-started) apps!
 
 ### Version update notifications {#version-updates}
 

docs/guides/installing-the-slack-cli-for-windows.md

@@ -7,9 +7,23 @@ slug: /tools/slack-cli/guides/installing-the-slack-cli-for-windows
 
 The Slack CLI is a useful tool for building Slack apps. This is your one-stop shop for installing this tool.
 
-:::warning[PowerShell is required for installing the Slack CLI on Windows machines; an alternative shell will not work.]
+<details>
+<summary>Prerequisite: installing PowerShell </summary>
+
+PowerShell is required for installing the Slack CLI on Windows machines; an alternative shell will not work.
+
+Run the following command to install PowerShell 7 on your machine:
+
+```pwsh
+iex "& { $(irm https://aka.ms/install-powershell.ps1) } -UseMSI"
+```
+
+The following articles may also be helpful should you run into any issues:
+
+- [Installing PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4)
+- [How to install and update PowerShell 6](https://www.thomasmaurer.ch/2019/03/how-to-install-and-update-powershell-6/)
 
-:::
+</details>
 
 <Tabs groupId="installation">
 <TabItem value="Automated" label="Automated Installation">
@@ -109,16 +123,3 @@ Using slack v4.0.1
 
 </TabItem>
 </Tabs>
-
-## Installing PowerShell {#powershell}
-
-Run the following command to install PowerShell 7 on your machine:
-
-```pwsh
-iex "& { $(irm https://aka.ms/install-powershell.ps1) } -UseMSI"
-```
-
-The following articles may also be helpful should you run into any issues:
-
-- [Installing PowerShell on Windows](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4)
-- [How to install and update PowerShell 6](https://www.thomasmaurer.ch/2019/03/how-to-install-and-update-powershell-6/)

docs/guides/removing-an-app.md

@@ -11,7 +11,7 @@ All good things must come to an end. You can `uninstall` your app if you need to
 
 ## Uninstall an app from your team {#uninstall-app}
 
-Removing an app from a workspace doesn't have to be a permanent decision. Sometimes uninstalling the app to remove it's active presence in channels is sufficient! This option has the added benefit of reinstallation at a later time without recreating the entire app.
+Removing an app from a workspace doesn't have to be a permanent decision. Sometimes uninstalling the app to remove its active presence in channels is sufficient! This option has the added benefit of reinstallation at a later time without recreating the entire app.
 
 To uninstall an app using the CLI, use the [`uninstall`](/tools/slack-cli/reference/commands/slack_app_uninstall/) command. Then, choose the workspace you want to remove the app from:
 

docs/guides/troubleshooting-slack-cli-errors.md

@@ -1,8 +1,11 @@
 # Slack CLI
 
-The Slack command-line interface (CLI) allows you to create and manage Slack apps from the command line. Use it in combination with the Deno Slack SDK, or the Bolt frameworks for JavaScript and Python.
+The Slack command-line interface (CLI) allows you to create and manage Slack apps from the command line. Use it in combination with the Bolt frameworks for JavaScript and Python, or the Deno Slack SDK.
 
-Follow the installation guide for either [MacOS / Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) or [Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows) to get set up. Then, follow the the [Authorization guide](/tools/slack-cli/guides/authorizing-the-slack-cli) to connect your workspace. 
+:::tip[Follow our [quickstart guide](/quickstart) to get set up with the Slack CLI and have a working app using the Bolt frameworks!]
+:::
+
+For more detailed instructions, follow the installation guide for either [MacOS / Linux](/tools/slack-cli/guides/installing-the-slack-cli-for-mac-and-linux) or [Windows](/tools/slack-cli/guides/installing-the-slack-cli-for-windows). Then, follow the the [Authorization guide](/tools/slack-cli/guides/authorizing-the-slack-cli) to connect your workspace. 
 
 ## Getting help
 

docs/guides/using-slack-cli-with-bolt-frameworks.md

@@ -2,29 +2,24 @@
 
 Communication between the CLI and the application SDK is managed by a project-level configuration file called `hooks.json`. This file is included in our app templates and defines script _hooks_.
 
-Hooks are small scripts that are _executed_ by the CLI and _implemented_ by the SDK. These commands perform actions on the project.
-
-The `hooks.json` file allows the CLI and SDK a standard way to communicate while remaining decoupled and abstracted. This interface is a key design of the Slack CLI: many application and project level tasks are delegated from the CLI to the SDK. This delegation, decoupling and abstraction allows for language-agnostic SDK implementations.
-
-## Core concepts {#core-concepts}
-
-### Hooks: How the CLI and the SDK communicate {#communication}
-
-Hooks are scripts that execute when a specific event happens or a Slack CLI command is invoked.
+Hooks are small scripts that are _executed_ by the CLI and _implemented_ by the SDK when a specific event happens or a Slack CLI command is invoked. These scripts perform actions on the project.
 
 A hook script may be triggered when:
+- generating the app manifest.
+- bundling function code before deployment to Slack infrastructure.
+- handling an application event during local development runs.
+
+## Hooks: How the CLI and the SDK communicate {#communication}
 
-- generating the app manifest
-- bundling function code before deployment to Slack infrastructure
-- handling an application event during local development runs
+The `hooks.json` file allows the CLI and SDK a standard way to communicate while remaining decoupled and abstracted. This interface is a key design of the Slack CLI: many application and project level tasks are delegated from the CLI to the SDK. This delegation, decoupling and abstraction allows for language-agnostic SDK implementations.
 
 When an event occurs, the CLI will execute a hook script by spawning a separate process, possibly passing a JSON object through `STDIN` and/or other parameters via command line flags to the hook script process, and waiting for a JSON response via the spawned process’ `STDOUT`. This system is heavily inspired by git hooks.
 
 Since communication over hooks involves inter-process communication (one process running the CLI communicating with another process managed by the SDK ie. the hook), the exit code of the hook process signals success or failure to the CLI process. The CLI will assume an exit code of 0 from a hook process signals success, while any other exit code signals failure.
 
 Some hooks may return data as part of their functionality. The CLI will use the `STDOUT` and `STDERR` of the hook process to transmit its response. For details on how a hook process can shape its response, and delineate diagnostic data from response data, see the section on [protocol negotiation](#protocol).
 
-### Discover hook scripts and default configuration with `get-hooks` {#discover}
+## Discovering hook scripts and default configuration with `get-hooks` {#discover}
 
 In order for the CLI to reliably discover the hooks for the [Deno SDK](https://github.com/slackapi/deno-slack-sdk), [Bolt Frameworks](https://docs.slack.dev/tools/), and future community-driven SDKs, the CLI employs a service-discovery-like approach to querying the SDK for what functionality it supports.
 
@@ -34,7 +29,7 @@ App developers do not need to edit or change their `hooks.json` file when upgrad
 
 Refer to the [CLI-SDK JSON interface](#interface-format) section for other examples.
 
-### CLI-SDK protocol negotiation {#protocol}
+## CLI-SDK protocol negotiation {#protocol}
 
 As the needs of app developers evolve, so will the interface and the rules of communication between the CLI and the SDK. These rules are negotiated via the initial `get-hooks` handshake and are specified via the `protocol-version` field returned by the SDK.
 
@@ -45,7 +40,7 @@ At the time of writing, only two protocol versions are supported:
 
 If at any point protocol negotiation fails or does not adhere to the rules of communication, the CLI will fall back to using the default protocol.
 
-#### Working implementations of protocol negotiation
+### Working implementations of protocol negotiation
 
 - In the CLI:
   - [List of protocols supported by the CLI](https://github.com/slackapi/slack-cli/blob/d2349b6328820d2dcb01312abd4d8b3694f5137e/internal/hooks/protocol.go#L21-L22)
@@ -57,13 +52,13 @@ If at any point protocol negotiation fails or does not adhere to the rules of co
   - [node-slack-sdk’s implementation](https://github.com/slackapi/node-slack-sdk/blob/main/packages/cli-hooks/src/protocols.js)
   - [python-slack-sdk’s implementation](https://github.com/slackapi/python-slack-hooks/blob/main/slack_cli_hooks/protocol/__init__.py)
 
-### Ensuring backwards compatibility {#compatibility}
+## Ensuring backwards compatibility {#compatibility}
 
 A hook’s name space (CLI) and its associated script implementation (SDK) will change over time. This can break backwards compatibility and require App Developers to juggle different CLI versions and SDK versions in order to maintain compatibility. It’s a frustrating situation that can ruin the developer experience.
 
 An additive approach to hook names or configuration settings allows us to keep hooks backwards-compatible for as long as possible and allows for a smoother upgrade experience. This approach also allows for tools to provide generous timeframes for supporting old hooks vs. new ones, allowing for deprecation windows and gradual rollouts. For configuration settings, an additive approach is accomplished by adding new configuration values that are not Golang defaults (e.g. bool defaults to false).
 
-For example, the hook name `run-v2` may be the successor to the hook named `run`. The SDK can implement either hook and the CLI will trigger the latest version, possibly falling back to earlier versions of the hook where applicable. The CLI can also warn of impending removal of older hooks, providing hints to the developer when tooling behaviour changes.
+For example, the hook name `run-v2` may be the successor to the hook named `run`. The SDK can implement either hook and the CLI will trigger the latest version, possibly falling back to earlier versions of the hook where applicable. The CLI can also warn of impending removal of older hooks, providing hints to the developer when tooling behavior changes.
 
 ## Hook specification {#specification}