Fix #943: Incorporate Socket Mode as default for Getting Started guide

[srajiang]

Summary

Based on issue #943, this PR is a first stab at updating our Bolt for JS Getting Started guides to Socket Mode as default.

The motivation for making this change is to mitigate the common pain-points of setting up a static HTTP Request endpoint configuration (ngrok), and configuring those URLs in the various surfaces within app config.

Changes

• Adds Socket Mode setup instructions to getting_started.md and removes HTTP / Request URL-specific setup
• Adds a getting_started_http.md guide which is parallel to to the standard guide, located down below with the rest of tutorials, which retains instructions specific to setting up with HTTP.
• Corrects sp, punctuation and formatting to improve readability and break down large blocks of text
• Updates instructions for how to build project locally

Testing

• Navigate to /docs/ and bundle exec jekyll serve` to build the pages locally. I found this helpful to check how formatting was applying.

Requirements (place an x in each [ ])

• I've read and understood the Contributing Guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.

[codecov]

Codecov Report

Merging #990 (10d07d6) into main (2af66a2) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##             main     #990   +/-   ##
=======================================
  Coverage   66.41%   66.41%           
=======================================
  Files          13       13           
  Lines        1212     1212           
  Branches      357      357           
=======================================
  Hits          805      805           
  Misses        338      338           
  Partials       69       69           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 2af66a2...10d07d6. Read the comment docs.

[srajiang]

I opted to keep the Tokens and installing apps, and Setting up your project sections pretty much the same content-wise, since adding a ton of context around communication protocols right at the outset seemed intimidating. There are already several concepts being covered there. Instead, most of the context-setting around Socket Mode (vs. HTTP) I added to the the Setting up events section, since that is where the communication protocol really becomes relevant (from a conceptual standpoint).

Also thought that having the user do the basic setup in their project (without setting SocketMode or app token options) and then return back to add them as part of enabling Socket Mode might help with their learning about what's required and not.

Would love to know if folks think this strikes a good balance between accessibility (getting to Hello World faster) and informativeness (why Socket Mode for getting started, what are alternatives), and what improvements we can make if not!

[shaydewael]

These changes look great, and thanks for cleaning up spelling and grammar errors. I've Included some suggestions and thoughts—feel free to ignore the ones you don't agree with 😄

[stevengill]

Great work @srajiang!!

I've left a bit of feedback.

In terms of preserving http/ngrok steps, I think we should create a copy of the original getting started guide and name it something like Getting started with http or via http? It can live in the side menu near the bottom with the other guides. Then we can link to the http version in blurbs throughout this guide. This way, we provide multiple entry points to the http version of the guide, but don't need to mix in no socket mode content into this one. Thoughts @shaydewael?

[stevengill]

I think it would be good to add a blurb in this section about checking out the http getting started guide (assuming we go with the two guide approach).

[srajiang]

Yep, I've added some specific language to allow the user to "fork" into the alternate guide :)

[stevengill]

We could possibly mention that app-level tokens are commonly used for creating a websocket connection to the app

[stevengill]

For this guide, users will need both bot token and app-level token. App-level token for starting socket mode, bot token for interacting with the slack api. I agree that holding off introducing app-level-token until the socket mode section makes sense

[stevengill]

Another good place to link http getting started guide.

[srajiang]

In terms of preserving http/ngrok steps, I think we should create a copy of the original getting started guide and name it something like Getting started with http or via http? It can live in the side menu near the bottom with the other guides. Then we can link to the http version in blurbs throughout this guide. This way, we provide multiple entry points to the http version of the guide, but don't need to mix in no socket mode content into this one. Thoughts @shaydewael?

I've pushed some changes in line with this approach ☝️ and included a blurb that allows the reader to sort of "fork" into HTTP / Request URl setup in the "Setting up events" section . @stevengill @shaydewael what do we think? Will it work? 🙇‍♀️

[stevengill]

Looks great! Can you convert this to a regular PR so we can let the checks run. If all looks good, merge away!

Great work!!