Proposing changes in documentation to help inexperienced people run and debug code with Serverless

[aplathan]

Description

I am not a developer, and count myself as an inexperienced person in all DevOps related matters. The changes I'm proposing reflect the learning process I went through and the challenges I faced since I found Bolt and started writing my first Slack App two weeks ago.

I have no prior experience in Node.js or Serverless, and even though I had a general knowledge what Lambda is, I had never written or deployed one before. Since my slash command app may receive only a few events per day, I started googling how to write a Lambda based slack bot. That's how I found https://slack.dev/bolt-js/deployments/aws-lambda, and started following the tutorial.

I find Serverless to be very easy and intuitive to configure and use. It is really helpful framework, and is a great fit even for a simple beginner's tutorial.

Then to the actual suggestions, and reasons why I am proposing them.

1. Do not install Serverless via npm in the tutorial

Both https://github.com/slackapi/bolt-js/tree/main/examples/deploy-aws-lambda and https://slack.dev/bolt-js/deployments/aws-lambda use npm to install serverless, and npx to run the package. However, npx serverless deploy or npx serverless offline --noPrependStageInUrl is very slow to run, and waiting it to finish gets frustrating. Instead, Bolt documentation and examples should show how to install a standalone binary like it's done in Serverless Getting Started guide https://www.serverless.com/framework/docs/getting-started/.

Standalone serverless run offline and deploy commands in fraction of the time it takes to do the same when run using npx. It took me several days to figure this out. At one point I started wondering why launching npx serverless and npm install gives so similar output on the console, and then I realized npx is basically installing itself on every invocation.

Experienced developers or devops' likely know this, and wouldn't have faced the problem in the first place.

2. Do not instruct to deploy when making a change in your code

In "Deploy the app" chapter "4. Deploy an update" https://slack.dev/bolt-js/deployments/aws-lambda#deploy-the-app user is asked to change their code a little bit and then to deploy it with npx serverless deploy.

For experienced developers this is a nobrainer, but I believe it would be better to rewrite this part of the tutorial so that after the code change user tests it locally first by running serverless offline --noPrependStageInUrl. When tests pass, it is deployed to the cloud.

The previous chapter "3. Test your Slack app" and "4. Deploy an update" would benefit from some general tips that may not be obvious to everybody:

• When the app is running locally (i.e., serverless offline --noPrependStageInUrl hasn't been terminated), user can edit the app.js, save it and immediately test the change by invoking a new event from Slack. I stopped and restarted serverless offline dozens of times before realizing this. A real developer probably laughs at this point, but I'm sure it would be really beneficial to mention this.

• When you have made some code changes and tested them locally, you don't need to redeploy the whole CloudFormation stack, instead save some time and just deploy the function by serverless deploy function -f slack.

As said, these are self-evident for experienced developers. Before I figured these out the hard way, I kept thinking "why is it so slow and difficult to debug the code".

Best,
Antti

What type of issue is this? (place an x in one of the [ ])

• bug
• enhancement (feature request)
• question
• documentation related
• example code related
• testing related
• discussion

Requirements (place an x in each of the [ ])

• 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.
• I've searched for any related issues and avoided creating a duplicate issue.

---

Bug Report

Filling out the following details about bugs will help us solve your issue sooner.

Reproducible in:

package version:

node version:

OS version(s):

Steps to reproduce:

Expected result:

What you expected to happen

Actual result:

What actually happened

Attachments:

Logs, screenshots, screencast, sample project, funny gif, etc.

[github-actions]

👋 It looks like this issue has been open for 30 days with no activity. We'll mark this as stale for now, and wait 10 days for an update or for further comment before closing this issue out.

[srajiang]

@filmaj - You've mentioned in a few places on how to better educate folks less experienced with deploying in serverless environments in general, so I wanted to bring this suggestion to your attention.

[filmaj]

Thanks for bringing this up @srajiang, I think these are excellent suggestions @aplathan makes. I will try my hand at folding these suggestions back into the documentation.