From c375e22fb8a4efeaeaaec894f6c74d0445dcf06b Mon Sep 17 00:00:00 2001 From: Vipul Sharma Date: Sun, 7 Nov 2021 20:14:16 +0530 Subject: [PATCH] add: more documentation - restructured docs - add usage docs --- docs/deployment/crons.md | 40 ++++++++++++++++++ docs/deployment/deployment.md | 1 - docs/deployment/docker.md | 5 ++- docs/deployment/kubernetes.md | 3 +- docs/deployment/manual.md | 5 ++- docs/deployment/options.md | 12 ++++++ docs/development.md | 3 +- docs/roadmap.md | 2 +- docs/usage.md | 80 +++++++++++++++++++++++++++++++++++ 9 files changed, 143 insertions(+), 8 deletions(-) create mode 100644 docs/deployment/crons.md create mode 100644 docs/deployment/options.md create mode 100644 docs/usage.md diff --git a/docs/deployment/crons.md b/docs/deployment/crons.md new file mode 100644 index 0000000..3708639 --- /dev/null +++ b/docs/deployment/crons.md @@ -0,0 +1,40 @@ +--- +layout: default +title: Crons +nav_order: 2 +parent: Deployment +--- + +Slate provides APIs to notify users, publish standup to Slack etc. One way to +schedule these notifications and publishing time is via crons. + +To publish standup submissions you can use the following approach: +- Kubernetes crons (in case you went with K8s based installation). +- Calling publish standup API via a cron or manually to publish to Slack + channel. + +## Kubernetes crons + +Follow the doc [here][k8s-crons] to setup required crons for Kubernetes cluster +deployment. + +## Generic crons + +### 1. Cron to notify users + +```bash +30 7 * * 1-5 curl --location --request GET 'https:///api/notify_users//' --header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' +``` + +This will set a cron to notify users every Monday to Friday at 7:30 UTC. + +### 2. Cron to publish standup submissions + +```bash +30 8 * * 1-5 curl --location --request GET 'https:///slack/publish_standup//' --header 'Authorization: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' +``` + +This will publish all the standup submissions every Monday to Friday at 8:30 +UTC to the Slack channel configured. + +[k8s-crons]: ./kubernetes.html#configuring-k8s-crons diff --git a/docs/deployment/deployment.md b/docs/deployment/deployment.md index 9ae663c..2fe0210 100644 --- a/docs/deployment/deployment.md +++ b/docs/deployment/deployment.md @@ -8,4 +8,3 @@ permalink: docs/deployment # Deployment -Following are the ways which you can deploy slate for yourself. diff --git a/docs/deployment/docker.md b/docs/deployment/docker.md index 8ecdba2..a5412cd 100644 --- a/docs/deployment/docker.md +++ b/docs/deployment/docker.md @@ -1,7 +1,8 @@ --- layout: default title: Docker -parent: Deployment +parent: Options +grand_parent: Deployment --- ## Docker @@ -12,7 +13,7 @@ docker-compose up Pre-built image at: https://hub.docker.com/repository/docker/vipul20/slack-standup -Make sure to update the following environment variables in [`docker-compose.yml`](./docker-compose.yml) +Make sure to update the following environment variables in [`docker-compose.yml`](https://github.com/vipul-sharma20/slate/blob/master/docker-compose.yml) #### Slack tokens diff --git a/docs/deployment/kubernetes.md b/docs/deployment/kubernetes.md index bedf69b..aa58d91 100644 --- a/docs/deployment/kubernetes.md +++ b/docs/deployment/kubernetes.md @@ -1,7 +1,8 @@ --- layout: default title: Kubernetes -parent: Deployment +parent: Options +grand_parent: Deployment --- ## Kubernetes diff --git a/docs/deployment/manual.md b/docs/deployment/manual.md index dbc4f96..680316f 100644 --- a/docs/deployment/manual.md +++ b/docs/deployment/manual.md @@ -1,10 +1,11 @@ --- layout: default title: Manual -parent: Deployment +parent: Options +grand_parent: Deployment --- ## Manual -Check the [development doc](./development) if you want to manually setup the standup bot or looking for development. +Check the [development doc](/slate/docs/development) if you want to manually setup the standup bot or looking for development. diff --git a/docs/deployment/options.md b/docs/deployment/options.md new file mode 100644 index 0000000..800eb42 --- /dev/null +++ b/docs/deployment/options.md @@ -0,0 +1,12 @@ +--- +layout: default +title: Options +nav_order: 1 +has_children: true +parent: Deployment +--- + +# Deployment Options + +Following are the ways which you can deploy slate for yourself. You can choose +either of them as per your convenience. diff --git a/docs/development.md b/docs/development.md index 1eabdba..5f98bbd 100644 --- a/docs/development.md +++ b/docs/development.md @@ -42,7 +42,8 @@ flask run --host 0.0.0.0 --port 5000 ## Install on Slack -To test this development deployment, install this to your Slack workspace by following the doc [here](./Installation). +To test this development deployment, install this to your Slack workspace by +following the doc [here](./Installation). You can expose the local server via [ngrok](https://ngrok.com/) for test purposes like below ``` diff --git a/docs/roadmap.md b/docs/roadmap.md index 6c77011..e0289a4 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,7 +1,7 @@ --- layout: default title: Roadmap -nav_order: 5 +nav_order: 6 --- # Roadmap diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..285faa3 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,80 @@ +--- +layout: default +title: Usage +nav_order: 5 +--- + +# Usage + +This page explains basic usage pattern of Slate. + +--- + +## Creating new / editing existing standup + +Use slash command `/standup configure` (or `/ configure` in case you configure a different name when you install the app). + +This will open a dialog box like below where you can: +- Add users you want in this standup. +- Set questions for the standup, each line separated. +- The channel where the standup submissions should be posted. +- The time at which the standup submissions should be posted. + +This dialog box view looks like the screenshot below. + +

Standup configuration dialog box (new/existing)

+

+ +--- + +## Submitting standup + +### Using slash command + +Use slash command `/standup ` (or `/ ` in case you +configure a different name when you install the app) to open up a dialog box +where you can submit your standup. + +### Using pre-scheduled cron notifications + +In case you schedule [crons][crons] for notifications, you'll get a Slack +notification like below. + +

Daily user notification for standup submission

+

+ +You can click on "Open Dialog" and submit your standup. + +Screenshot of the dialog box is below. + +

Standup submission dialog box

+

+ +--- + +## Publishing standup + +### Using pre-scheduled crons + +Check the [crons][crons] to setup cron jobs for publishing standups. Published +crons on a Slack channel should look like below. + +

Standup publish view on channel (individual submissions in thread)

+

+ +Individual submission will be as messages in the thread. + +--- + +## Editing standup + +Once you submit your standup, you get a copy of your submission which you can +also edit it by clicking the "Edit" button. + +Your copy of submission looks like below. + +

Submission view in DM

+

+ + +[crons]: ./deployment/crons.html