Getting Started with Playbooks

It’s 2022: You’re good at your job, you’re maintaining modern systems, now you want to level up your team based on a solid foundation of their collective expertise. You want to standardize and centralize process documentation and make execution as easy and effective as possible so that everything runs smoothly, every time. In other words, you want to reduce the toil of understanding what, when, and how for structured processes so that everyone can let their skills shine and deliver predictable excellence.

Today, you may be using Mattermost (or another messaging tool) for team collaboration. Channels and messages have enabled you to share and communicate asynchronously, and you’re using some integrations for various organic workflows. Overall, things are largely unstructured or ad hoc in this space.

Your challenge is that many digital processes require both collaboration and formal structure to reliably deliver desired outcomes. Some workflows, like software QA, testing, and delivery, need to follow well-defined steps that each have clear ownership but are part of a team-wide effort. Repeatable processes such as onboarding, incident response and management, and quarterly roadmap updates need to move smoothly through many tasks and assignees, but suffer from irregular handoffs and check-ins. Documentation and support for these workflows is scattered across systems, resulting in skipped steps and communication errors.

To solve this, you can use a tool available in every instance of Mattermost that combines collaborative checklists with integrated, channel-based communication, automations, and reporting: Playbooks.

Well-documented and executed workflow orchestration can set your team apart when it comes to developer and business success. A playbook is a living entity that not only aids in visibility and adherence to a process, but allows your team to learn and improve together with every iteration. Automation and faster software will only get you so far, while giving an entire team or organization context and clear communication in a single location will enable alignment and efficient workflow execution for the long term.

In this guide we’ll familiarize you with Playbooks and show how you can get started using them today. You’ll get a quick tour and some highlights of basic usage.

Table of Contents

• What are playbooks?
• Playbook architecture
• Hands on time
  • Video walkthrough
  • Create a new playbook
  • Use your new playbook
  • Completing a run
• Outcome: Continuous improvement for all
• Resources

What are playbooks?

First, you’ll need a recent version of Mattermost (v 6.0+). For this guide we recommend creating a free account on our open source community server so you can follow along with links and examples. The Mattermost Community server is where open source work on the platform happens publicly using the same tools we’re building. For a good example, check out the playbook we use to release Playbooks features. 

You’ll find Playbooks in the Mattermost global menu in the upper left corner (“bento box” style grid of squares). On the Playbooks dashboard you’ll see a tab for active runs and a tab for playbooks, which includes standard templates and any shared custom playbooks.

When you first click into an existing playbook from the dashboard you’ll see a preview page with a description, the checklists that make up the playbook, and some menu items to take further action such as editing, creating a run, or seeing previous runs to date. In the “Playbooks Team: Feature Swimlane” playbook, you can click into the Usage tab, then click a finished run. Take a look at the overview and updates, then go to the associated channel by clicking Go to channel in the upper right. This opens the dedicated run channel displayed alongside the checklist for the run.

When you want to use an existing playbook yourself, you’ll create a new run by clicking the run button in the upper right hand corner of a playbook preview page. This creates a new copy of the playbook and opens up the side-by-side view of the checklist with the paired channel for the current run. You can modify the run, add team members or stakeholders to the channel, complete tasks, discuss progress, and post updates on how the run is going. When you’re ready to create a customized playbook, read on below.

A quick recap on playbook architecture

Playbooks are a powerful tool, so there are a few layers involved! To quickly review we have:

• Template – a simple and generic starting point
  • Playbook – the source copy of your repeatable process
    • Run – a single instance of your repeatable process

Hands on time with Playbooks

tl;dr Watch a video of all the steps below!

Create a new playbook:

1. From your Playbooks dashboard, select the “Feature Lifecycle” template. [EDIT: Since the video was recorded the templates have moved to the bottom of the Playbooks tab. Scroll down, and give the “Learn how to use Playbooks” template a try sometime, too!]
2. Set your playbook to private since we’re testing, and give it a quick name and a description so you can see how these fields are used in subsequent views. Click Create Playbook.

3. In the next screen, you’ll find configuration options in four tabs: Checklists, Actions, Status Updates, Retrospective. Let’s start under Checklist. 
   1. This template uses subsections to represent different stages of the process. Minimize these with the carets on the left side to see the big picture.
4. Let’s add an action item with a small automation. 
   1. At the end of the Kickoff section click +New task. Name the task Remind channel to prep for first meeting.
   2. Click +Add a slash command and enter /echo @channel Heads up to start planning for our feature kickoff meeting!
   3. Now drag this task (using the grab bars that appear to the left on hover) up to the top of the Kickoff section.
   4. Feel free to edit and add more tasks while you’re here. There are many slash commands available in Mattermost and integrations that can be used here.
5. Now click on the Actions tab.
   1. When a run starts, a channel will be automatically created. Make this channel Private for every run with the radio button to the right.
   2. Slide the toggle for Invite members to the right to activate it.
   3. This is where you could add cross-functional team leads or everyone on a feature dev team. Keep in mind that we’re creating a reusable playbook, so think about who should always be involved in this process – maybe a product manager and the engineering lead? For now let’s just add your own username here, or any friends you have on the server who’ve agreed to help out.
6. Click Save. Now you have a customized Feature Lifecycle playbook!

Use your new playbook:

1. Create a run by clicking the Run button in the upper right. 
   1. Look at that, you’re the owner! Name your run.
   2. Now you’ll see the side-by-side view of the checklist you edited earlier and a private messaging channel that is specific to this run of your playbook. The right-hand sidebar with the Run details and Checklists can be toggled with the clipboard icon.
   3. Add additional participants in the sidebar. Anyone who was added in the earlier actions tab was automatically added to this run channel. Anyone who has selected auto-follow runs from the playbook preview page will be notified when a new run starts but not added to the channel.
   4. If you navigate away from the channel, return by finding the channel in the left-hand sidebar channel list, or by clicking the global menu in the top left and selecting Playbooks. Your runs in progress will display on this dashboard, or visit the Playbooks tab>[My First Playbook]>Usage>[My first playbook run]>Go to channel. 
   5. You will also meet the Playbooks Bot, which aggregates Playbooks notifications from all the runs you’re participating in into one private conversation with the bot.

2. Let’s assign some tasks. Hover over any of the checklist items and click the avatar with a + on it (hover text “Assign”). Assign yourself or anyone who has volunteered for your experiment. Assigned tasks will appear in a direct message from the Playbooks bot when they are assigned, when they have not yet been completed, or if you run the command /playbook todo in any channel.
   💡Every task should be assigned so there are no questions or gaps in ownership. At Mattermost, we assign tasks when they are ready to execute, with unassigned tasks implicitly owned by the run owner to decide how to proceed.
3. Now we’ll complete a task. In the checklist under Kickoff you’ll see the task we edited earlier. Click Run to instantly post that message to the channel. Now everyone has been notified of kickoff with the @channel message. Click the checkbox next to the task to mark it complete.
4. This template comes with some useful steps that highlight best practices for shipping features. For example, “Choose an engineering owner for the feature”: Reassign ownership of the run to another participant in the sidebar Run details. “Break down feature milestones and add them to this checklist”: use the + task button available on hover on checklist headers to add tasks on the fly. 

5. Add a message from Channels to the run timeline:
   1. Navigate to any message, anywhere in Channels. Maybe a DM to yourself, or the latest from Reception. Hover and click the three dots to the right over the message. Click Add to run timeline and select your run.
   2. View this addition by navigating to the run overview page. Click the three dot menu that appears on hover next to the run name in the channel sidebar, then Go to run overview.
   3. In the Retrospective tab, filter the timeline to show all events. The message you just added will appear in the timeline in chronological order, so if the message was posted before the run started, it will appear at the top (beginning) of the timeline. Click the message in the timeline to jump to that message in Channels, or remove it from the timeline with the trash can icon.

6. Post a status update for the run:
   1. From the side-by-side view, click the Post update button in the sidebar. Using markdown for formatting, write a note to yourself on how this experiment is going so far. Reset the timer at the bottom by typing “in 5 minutes” and click Post update. The update appears in the channel, the Playbooks bot will share it to participants and anyone auto-following the playbook individually, and it appears in the run timeline.
   2. In five minutes you’ll get a ping from the Playbooks Bot to post your next status update. Hit snooze or fill it in.

Completing a run:

1. Continue editing and checking off tasks as much as you like here. 
2. At the bottom of the checklist, click the button Finish run. The Playbooks bot will post a message in the run channel asking if you want to fill out a retrospective. Click Yes.
   1. Here you can fill in as much info as you wish using markdown in the Report field, referring to the timeline on the right for a reminder of what was done. Save your retro. Information on individual runs is always available on the overview and retro pages for each run of a playbook. We’ll go into greater detail on the retrospective function in a future guide. 

3. Now that you’ve run a run, take a look at the aggregated data starting to populate the usage tab for your playbook. As you continue to use the playbook and complete more runs, you’ll be able to analyze the effectiveness of the playbook by looking at the number of tasks finished next to each run in the table, the regularity of the runs, the duration, and the number of active participants.

What next?

1. How did it go? What does your team agree should be changed for all future runs? Make those edits to your playbook so they are propagated in subsequent runs.

Playbooks enable continuous improvement for all

Playbooks allow you to connect all the pieces of your process in one place. In doing so, you also create a record for you and your team to review and iterate on. Team members can confidently execute a process on their own when others are out of the office or when an incident occurs in the wee hours. Senior team members can onboard and enable others by systematizing their knowledge and experience and sharing it openly. For any lengthier processes with action items and retrospectives, you now have additional capacity and ability for continuous improvement.

When you’re ready to create your own playbook, you can start from one of the templates and edit away, or start from scratch. We recommended outlining the steps with your team or yourself so you know what your needs and goals are, then building out your playbook. We’ve just scratched the surface, hopefully you’re now buzzing with ideas for ways playbooks can help your organization. 

Resources

Playbooks in the Mattermost documentation

The Mattermost Roadmap

The latest on Playbooks permissions

The Ask Anything community channel

Coming soon: An Advanced Guide to Playbooks!