clean the README file

Author: fharper

README.md

@@ -1,69 +1,68 @@
 # Slack Warm Welcome App
 
-This application is helping anyone manage a Slack community semi-automate, in a less obvious, and more human way, welcome new members.
+Semi-automated, welcome messages for new Slack community members. When someone joins, you get a DM with buttons to send one of your predefined welcome messages — so it looks personal, but takes one click and you can do it only when you are online.
 
-## Goal
+## Why
 
-It's a matter of personal opinion, but personally, there is nothing I find less welcoming than receiving a welcome message from a bot when I join a new community. There is also the clearly automated message, but coming from the community manager, founder or developer advocate, sent at like 3AM their time. It's a bit better than from a bot, but it's not there yet. Since communities are all about humans, but welcoming everyone manually is time consuming, even if I consider it to be super important for a healthy community.
+When joining a community, there is nothing I find less welcoming than receiving a generic message from a bot (except for sharing the code of conduct & some guidelines) or even a lovely message from the community manager while they are clearly not online. Since communities are all about human connections, I firmly believe that it's really important to properly welcome people. To help me do this easily, I created this Slack application. I can now send some love to the new members, when I'm online and have time to discuss with them if they reply without being afraid of forgetting anyone.
 
-I created this Slack application to help me welcome new members on my Slack community in a more human way while making it as easy and not time consuming at all. Here is how it works:
+## How It Works
 
-- When John Doe, a new member, join the community, Slack is firing an event that is sent to the application;
-- The application send the person responsible for welcoming new users (configured in the [.env file](.env)), in that instance, me, a message saying that John Doe just joined the community;
-- The message sent, contains a button to welcome John Doe directly;
-- When I'm online, and I have time to answer any of their question, I then press the button, and a predefined welcome message (configured in the [.env file](.env)) is sent to John Doe, which include his full name;
-- This process is repeated every time someone joins, so if two people joined while you were busy, once you're back on your Slack community, you'll see two messages with two buttons to press as you wish.
+1. A new member joins your Slack workspace.
+2. You receive a DM mentioning their name and a button for each welcome message you configured.
+3. You click a button when you're online and ready — the message is sent as a DM from you, not a bot.
 
-## Installation
+## Setup
 
-### Node.js Application
+### 1. Create the Slack App
 
-First, you need to run the application on a cloud provider: you could run it locally but it needs to be accessible from the internet so Slack can send events to it. You will need to have [Node.js](https://nodejs.org), and [npm](https://www.npmjs.com) running on your cloud provider. Once you are ready to install the application, you can either clone this repository using the `git clone git@github.com:fharper/warm-welcome.git` command or you can just download the latest [release](https://github.com/fharper/warm-welcome/releases). Once the files are in place, run `npm install` to install all the dependencies. Be sure to update the following variable in the [.env file](.env)):
+1. Go to [Your Apps](https://api.slack.com/apps) and click `Create an app` > `From an app manifest`.
+2. Pick your workspace and click `Next`.
+3. Update [manifest.yml](manifest.yml): replace `YOUR-APP-DOMAIN-GOES.HERE` with your app's domain in `redirect_urls`, `event_subscriptions > request_url`, and `interactivity > request_url`. Optionally change the app `name`, `description`, and `display_name`.
+4. On step 2, click `YAML`, paste the content of [manifest.yml](manifest.yml), click `Next`, then `Create`.
+5. Click `Install to Workspace`.
 
-- **YOUR_USER_ID**: to get the user ID of the person who will send the welcome message, click on their name (either within a channel, or at the top of a direct message). On the left pane that opened, click on the three vertical dots, and choose `Copy member ID`. If it's yourself, click on your profile icon at the top right of Slack, and follow the same steps.
--**WELCOME_PART1** & **WELCOME_PART2**: the automated message is built with two parts, `WELCOME_PART1` being the text before the new user's full name, and `WELCOME_PART2` the text after.
+> If you later change the URL in the manifest, verify the event URL by running `./node_modules/.bin/slack-verify --secret SLACK_SIGNING_SECRET` with your actual signing secret.
 
-_Future versions of this app will probably use templating, so this stupid implementation of `WELCOME_PART1` & `WELCOME_PART2` will be things of the past._
+### 2. Configure the .env File
 
-#### Run
+Copy  [.env.example](.env.example) to [.env](.env) and fill the following:
 
-Once it's done, you can run the application using the `node index.js` command. You would be advised to run it as a service to ensure it's always running, and restart when there is an issue (running it with something like [pm2](https://github.com/Unitech/pm2) `pm2 start index.js`). Note that the app won't work at first as you need to update the other variables from the [.env file](.env)), but you won't be able to do it before you create the Slack application.
+| Variable | Where to find it |
+| --- | --- |
+| `SLACK_SIGNING_SECRET` | Settings > Basic Information > App Credentials > Signing Secret |
+| `SLACK_BOT_TOKEN` | Features > OAuth & Permissions > Bot User OAuth Token |
+| `YOUR_USER_TOKEN` | Features > OAuth & Permissions > User OAuth Token |
+| `YOUR_USER_ID` | Click on your profile in Slack > three dots > Copy member ID |
 
-#### Docker
+#### Welcome Messages
 
-You can also run the application using Docker
+Configure up to 3 messages using the format `Label|||message text`. Use `{{name}}` as a placeholder for the new member's first name:
 
 ```shell
-docker build -t warm-welcome .
-docker run -p 80:8080 warm-welcome
+MESSAGE="Welcome|||Welcome {{name}}! Happy to have you here."
+MESSAGE_2="Employee|||Hey {{name}}! Be sure to read the internal guidelines."
+MESSAGE_3="Casual|||What's up {{name}}!"
 ```
 
-### Slack Application
-
-First, you need to create a new Slack application. To do so, connect to your Slack Workspace in the browser, and go to [Your Apps](https://api.slack.com/apps). Click on the `Create an app` button, and choose the second option named `From an app manifest`. On step 1 of 3 screens, pick the workspace you want to welcome people, and click `Next`.
-
-Before the step 2, update the [manifest.yml](manifest.yml) file with the proper URL for your application. You need to update the `YOUR-APP-DOMAIN-GOES.HERE` part of the following members:
-
-- `redirect_urls` from the `oauth_config` parent;
-- `request_url` from the `settings > event_subscriptions` parent member;
-- `request_url` from the `settings > interactivity` parent member.
-
-Do not change the second part of the URL. Feel free to change the members `name` & `description` from the `display_information` parent to an application name and description that you prefer. You can also change the `display_name` member from the `bot_user > features` parent for a preferred bot name.
-
-On the step 2 of 3 screen, click on `YAML`, overwrite the text with the content from the [manifest.yml](manifest.yml) file, and click `Next`. On the last screen, step 3 of 3, please validate that all the information is OK, and click the `Create` button. On the `Basic Information` screen, click on the "Install to Workspace" button. It will install the app to the workspace, and add the warm-welcome bot to it. Don't close this page yet, you'll need it for the next step.
+Each message gets its own button in the DM you receive.
 
-> If at some point, you update the URL in the Slack application manifest, you'll be asked to verify the event URL. To do so, run `./node_modules/.bin/slack-verify --secret SLACK_SIGNING_SECRET` while replacing `SLACK_SIGNING_SECRET` with the `Signing Secret` value. Please read the next section to learn how to get that value.
+### 3. Run the App
 
-### Node.js Application Configuration
+```shell
+npm install
+node index.js
+```
 
-Now that the Slack application is deployed, you need to update the configurations in the `.env` file from the information found on the page you kept open. Don't worry, it's the last step!
+Or with [pm2](https://github.com/Unitech/pm2) for persistence: `pm2 start index.js`
 
-- **SLACK_SIGNING_SECRET**: from the `Settings` menu choose `Basic Information` (you should already be on that page). Under the `App Credentials` section, get the `Signing Secret` value;
-- **YOUR_USER_TOKEN**: from the same page, under the `Building Apps for Slack` section, expend the `Add features and functionality` subsection, and click on `Permissions` which will bring you to the `OAuth & Permissions` page. On that page, under the `OAuth Tokens for Your Workspace` section, copy the value of `User OAuth Token`;
-- **SLACK_BOT_TOKEN**: now copy the `Bot User OAuth Token` value.
+#### Docker
 
-Once you completed these steps, everything should be working. Congratulations!
+```shell
+docker build -t warm-welcome .
+docker run -p 80:8080 warm-welcome
+```
 
 ### Testing
 
- If you want to test if everything is working, join your Slack community as a new user. At that point, the bot named `warm-welcome` (of the name you gave it in the [manifest.yml](manifest.yml) file) should send you a message in the form of `john-doe joined Slack! Welcome the new user now?` with a green `Now` button. If you press the button, John Doe will receive your message. If one of these steps isn't working, check the log from your web server as there's probably something wrong with the Node.js app. If the logs are fine, check if the app can be reachable from outside of your server, and validate the information on the Slack application page named `App Manifest` under the `Features` section.
+Join your Slack community as a new user. You should receive a DM with buttons for each configured message. Click one of the message button and the new member gets your welcome message. Check your server logs if something isn't working.