Using Discourse with Slack

EdgeX Foundry uses Discourse as a complementary system Slack, not as a replacement or alternative. Both systems provide a unique set of features that are useful for building and supporting a developer community. The makers of Discourse provide an excellent guide to effectively using Discourse together with a real-time chat system.

Additionally, Discourse provides a Slack integration plugin that makes it easier to use the two services together. This integration can be controlled through the new /discourse command in Slack.

New topic notifications

The integration plugin allows posting notification messages in a Slack channel for new activity in Discourse. You can request notifications for only new topics posted under a specified category, new topics and new comments, or new comments that tag a specific person or group. Because this could cause a lot of noise in the Slack channel, in most cases it’s recommended to only receive notifications for new topics.

The initial setup of Discourse includes the following notifications:

  • New topics in the Core category will be posted in core on Slack
  • New topics in the Devices category will be posted in device-services on Slack
  • New topics in the Applications category will be posted in applications on Slack
  • New topics in the DevKits category will be posted in devkits on Slack
  • New topics in General (uncategorized) will be posted in general on Slack

To add new notifications to Slack, use /discourse follow <category> in the Slack channel you want to receive those notifications.

Moving discussions to Discourse

Because Discourse content will not go away, and it is easier for new people to find and search, we want to move as much of our support discussions there as possible in order to build up a knowledge base for community support. Many of these support conversations will naturally start in Slack, and it would be a poor user experience if we tell new people to repost their question in Discourse before we help them.

Fortunately, the integration plugin provides a way for us to easily move those conversations into Discourse after they happen in Slack, so we can preserve them without making the new user do it themselves. At any point in the conversation you can use the /discourse post <n> command in the channel, it will then grab the most recent <n> messages and create a new draft post in Discourse. Once in the draft stage you can edit the message to remove unrelated content or add context. You should also choose the right category for the post at this state, and give it a meaningful title.

You should post a conversation to Slack when it:

  • Has a clear description of what the problem is and what part of EdgeX it originated from
    (So it can be properly described and categorized in Discourse)
  • Is a support topic that can likely be solved without a code change in EdgeX
    (If it is a bug requiring a code change, it should be made into a Github Issue)
  • Is a support topic that might be encountered by other users in the future
    (If it isn’t just that the user made an unusual mistake or has an unusual setup)
  • Is not easily answered by referring to existing documentation
    (If we already answer “How do I do X?” in the docs, just link to that)

If you push a Slack conversation to a Discourse topic that is configured to notify a Slack channel of new topics, that channel will receive the notification with a link to the new Discourse thread. Otherwise you should provide the link in the channel yourself so that the people participating in the discussion, or just following along with it, can see that it has been move.

WARNING: The post command will only capture comments in the channel, it can not capture comments in Slack threads, so try to avoid threading when providing support in Slack.