Skip to content
AssemblyAI Logo AssemblyAI Playbooks
GitHub

How to Create a Playbook

Introduction (What is a Playbook)

A playbook is a document that provides step-by-step instructions and guidance on how to complete a task or respond to a situation. It can be a valuable tool for organizations, teams, and individuals to ensure that they have a clear and effective plan in place for a variety of situations.

Playbook Structure

When creating a playbook, it is important to structure the information in a clear and organized manner. In most cases, a playbook should include the following sections:

  • Introduction

  • Procedures

  • Resources

  • Appendices

Definitions

Introduction

The introduction should provide an overview of the purpose and scope of the playbook, as well as any relevant background information needed to understand the playbook.

Procedures

The procedures section should outline the step-by-step instructions for performing the task or responding to the situation covered in the playbook. Each step should include detailed instructions, what tools and resources are needed, and any potential challenges or considerations.

NOTE: Screen shots and links are worth 1000 words; use them generously.

Resources

The resources section should include a list of any materials that may be needed to complete the procedures outlined in the playbook. This can include links to reference materials, instructions for using specific tools, and contact information for relevant individuals or teams.

Appendices

The appendices section should include any additional information or supporting materials that may be relevant to the playbook. This can include diagrams, flowcharts, examples, a glossary of terms, or a list of abbreviations.

Where do we store playbooks?

Playbooks are stored in the flow monorepo. Check out the Procedures section below for a step-by-step walkthrough of how to create a playbook.

Procedures

1. Create a New Markdown File

  • Use your preferred Markdown editor.
    • Optional: If you’re more comfortable in Google Docs, create your playbook there first, then go to File > Download > Markdown (.md) when you’re ready to convert.
  • Make sure your file starts with frontmatter like this:
---
title: "How to Escalate a Bug to Engineering"
---

2. Write Your Playbook Content

Include the following sections:

  • Introduction – Context and purpose
  • Procedures – Step-by-step instructions
  • Resources – Links, tools, or assets needed
  • Appendices – Any extra info (optional)

3. Create a Pull Request

  • Add the Markdown file to the appropriate folder in the Git repo (e.g. /src/content/Various How To Playbooks/).
  • Commit your changes and open a PR with a clear title and description.
  • Tag a Support Engineer for review before merging.

4. Review & Approve

  • Another Support Engineer should review your PR for:
    • Accuracy
    • Clarity
    • Formatting consistency
  • Once approved, the playbook can be merged into main.

Additional Notes

  • Naming: Use a clear, descriptive filename like escalate-bug-to-eng.md
  • Searchability: Your playbook title (in the frontmatter) will be used for indexing and display on the site.

Conclusion

By following this outline, you can create a comprehensive and effective playbook that provides clear and concise guidance on how to complete a task or respond to a situation. A well-structured playbook can be a valuable asset, helping us to prepare for and respond to a variety of situations efficiently and effectively.