Unlocking buried company knowledge with a custom Slack app
How Deliveroo uses the platform to search for business acronyms and terminology in Slack
November 2019 Update: The Whatis bot is now available as a standalone Slack app!
tl;dr: the Deliveroo Business Automation Engineering team were able to use Slack Dialogs, Message Actions and Attachments to quickly build an internal application (bot) for discovering the meaning of internal business terminology — previously a significant source of distraction and lost productivity.
“Our APAC ERAT was down 7 bps after project Freddie was rolled out to customer Gpop, would you mind raising this on the comms channel?”
Many readers will have experienced the terror of not knowing the meaning of one or more pieces of business terminology used in a discussion. Important messages are often missed in fear of derailing the conversation or highlighting the ignorance of a term everyone else seems familiar with, and time can be wasted after the fact searching for definitions.
The siloed nature of growth at many companies means that common (across silos) sources of distraction are often overlooked or under-prioritized. In order to tackle this issue and the many productivity trials of being a hypergrowth company, Deliveroo created the Business Automation Engineering (BAE) team.
The BAE team works cross-functionally to quantify areas lacking in operational efficiency and either build out internal automation solutions or prioritize the issue to another relevant product team. By working cross-functionally aggregate sources of distraction come to light — small productivity drains that on their own may not seem significant, but which are damaging when their effects are considered in aggregate.
How bad was the problem?
A source of significant distraction as Deliveroo develops and expands is the proliferation of Business Terminology (BT). We define BT as those collections of Acronyms, Phrases or project names that are used to refer to various business or technical processes (AOD, RET, PMF, Project Freddie, Happy Customer…. the list goes on). Compounding the effect of BT growth is the fact that many new joiners arrive each week and need to get up to speed with their team’s terminology and that of the wider org.
As in other technology companies, many methods for keeping track of BT were attempted and in use. For example, a Slack channel was created where people could ask what things meant (its membership quickly grew to over 500 users), and a large shared Google sheet was created. It is poor practice to highlight an issue without backing it up with data and while it is exceedingly difficult to quantify how many aggregate full-time effective employee hours were wasted searching for terminology definitions, the diversity of methods developed internally to attempt to make terminology discovery easier implied a chronic issue.
Having terminology definitions in multiple locations resulted in duplicates and inconsistency between sources. A more serious complication, however, was the lack of a clear record of terminology ownership, or who had added or modified any given piece of BT — no person or team was accountable for their definitions. The lack of a source of terminology truth made the overall problem costlier still, as more experienced employees and managers, whose time should be spent on growth-driving activities, instead found themselves acting as a directory service and single point of failure for domain-specific knowledge.
The need for a convenient to access and easily updated centralized store of BT was apparent; how to build, present and deploy such an application was less clear. If only there was a platform that could easily provide a way of interacting with applications straight from our existing conversational interface?
The BAE team had already begun the process of making our productivity tools, normally run through scheduled jobs, available on-demand and so could leverage our new infrastructure towards the creation of an application to search for, create, update and delete company phrases and acronyms (A basic CRUD application). We will soon be launching an article on our awesome internal business automation tooling on the Deliveroo engineering blog!
Slack not only provides excellent prebuilt solutions for invoking each of these different database operations via message actions (buttons) and dialogs but also for performing the initial search in the most straightforward and structured way via a Slash Command — ours was aptly named /whatis in this case! It helped to have a short and entirely appropriate name for the slash command, so its name was synonymous with its usage “Can you add a whatis for EOD?”.
How terminology searching works
The user enters a lookup slash command /whatis <some piece of BT > sending a POST request to our lightweight server endpoint that responds immediately with a prompt back to the user that their BT is being looked-up (or a failure message if they did not enter any text).
The web server creates an event on an asynchronous task queue — passing through the text entered by the user and the response_url field of the original slash command request. The Asynchronous task queue finds a matching piece of BT from the consolidated BT database (sqlalchemy) and returns any matching results back to the user posting to the provided response_url!
Other terminology operations follow a similar pattern with each message action linked to a separate CRUD event, though some actions act to send a Slack Dialog to the user with the Update or Create new form.
I need specifics.
Each BT match is returned as a separate message attachment — this allows us to pass through update, rollback and delete message buttons for each piece of BT. There may be multiple matches for any piece of BT as there might be multiple meanings for each one. We decided that only BAE team members should have the ability to delete acronyms to prevent internal misuse and BAE team members or original BT creators should be the only ones with the ability to rollback acronyms (revert the definition to an earlier version). We can restrict the actions that different users see for each message using the user_id parameter sent by Slack and matching it against the users who are registered to our BAE private slack channel (permission via channel membership).
Each BT message attachment is given an update button where any user may edit the attributes of any piece of BT, this update will create a new BT database entry with a higher version number than its parent item (allowing updates to be rolled back). Pressing the update button will send a Slack Dialog to that action’s Trigger ID.
Each piece of BT is linked back to its entry in the BT SQL table via its message action button values where the BT ID and version are encoded as a tilde-separated string
MdTf~3. This value can then be separated when handling the button press event to look up the BT to update.
Presenting the different BT attributes (links, further notes etc… ) was easy using Slack message fields. We can encapsulate each attribute returned by our terminology lookup in a Slack Message Field so as not to predetermine a layout. Slack ID parsing gave us the benefit of adding a point of contact field to each BT item — this field is updated with the Slack ID of anyone who has created a BT item or updated an existing one. The point of contact feature also eliminates misuse as malicious items entered in the tool will have the enterer listed as the point of contact for that item.
Where art thou analytics?
Our infrastructure logs all terminology searches and their associated Slack metadata and exposes aggregate views of searches on internal dashboards — this gives Deliveroo managers the unique ability to be able to see what Deliveroo business actions are creating confusion or are most in need of documenting. We can even use the changes in our Terminology knowledge base to chart our organizational complexity over time!
Further to the above, it is sometimes what users are not able to find that is most useful to us — the same process that looks up BT also stores all BT searches that do not result in a match. We have a new tradition on our team where every few weeks we see if we can find definitions or owners for all the BT that people have been trying to search for.
Slack not only gave us a fantastic out-the-box interface for our internal productivity tools but its centrality to Deliveroo’s culture and daily communications also make it the ideal place to surface quick reference applications. The success of the /whatis bot has led to the development of a whole suite of BAE tools, primarily interfaced with via Slack with many more on the horizon!
Questions or feedback? Send a note to firstname.lastname@example.org or tweet @SlackAPI