In my last post, we discussed best practices for creating a script for your Alexa Skill. If you’re wondering what the heck an Alexa Skill is, check out my Alexa Skill 101 post here. If you missed Best Practices for Scripting Alexa Skills, you can wind it back here.

In this article, we will take the Alexa script you created in the last post, to create a requirements document for your Alexa Skill.

Why do we need requirements for Alexa Skills?

As any good product manager knows, a solid set of requirements is essential to communicate with your developer. We need to create a roadmap of how our Alexa skill will work. This exercise is also essential to have your skill approved by Amazon. I will cover Amazon skill certification in a future post. Similar to app development, a clear and complete set of requirements will minimize development time and costs.

Let’s start with an example. In this example, we are creating an interactive adventure for a child called Adventure Time. As we learned last week, the user launches the skill with the phrase “Alexa, launch Adventure Time.” Once the Alexa skill is launched, we want to present the user with 2 options. They can go to the BACKYARD or the SEA. If they want to go to the MOUNTAIN, we can’t expect Alexa to make up a story about a mountain on the spot, we need to direct the user to choose from the BACKYARD or the SEA. If the user chooses BACKYARD, they can either explore the grove or the fountain in the backyard. If they choose SEA, they can go to the tide pool or the beach. If you’re at the SEA, you can’t go to the grove, and vice versa you can’t get to the beach from the BACKYARD. Make sense? Let’s map this out visually in a tree diagram.

We quickly see that there are 3 states for this skill. Opening state, Backyard state, and Sea state. In each state, we have a defined set of options.

• Introduction: What does Alexa say when the user goes into each state?
• What are the options from that state?
• What if the user asks for help?
• How will Alexa handle a user input that is not one of the defined options?
• Exit – How will Alexa respond if the user says ‘Exit’ from this state?

Essentially, we need to script Alexa for every scenario in our skill.

If we don’t define the script for these scenarios, you will either end up with a skill that crashes, or the developer will be left to create a dialogue of their own creation that may or may not be in alignment with your brand. Do not leave your script to chance.

Continuing with our Adventure Time example, here’s how we would write requirements from our script following our tree diagram.

Note that we have created requirements for every possible scenario specific to the state the skill is currently in. If the user says something that Alexa doesn’t understand as one of the current options, Alexa is directed to say, “Sorry, I didn’t quite catch that.” followed by the current list of options. We created a speech for Alexa if the user says help at any point in the skill with the current options available to them. Help and Unhandled scenarios are required for Amazon certification.

In real-life, your skill will probably call an API and present a set of data that will be parsed and presented to the user. I recommend another column for the API call with fields, type and expected result. I will cover API skills in a future article. Stay tuned.

As you can see, requirements get lengthy pretty quickly just to cover the user scenarios. Let’s not forget the principles of good requirements documentation also include:

• Skill name
• Purpose
• Target Release
• Stakeholders / Team Members
• Team Goals and Business Objectives
• Overview description of the skill
• Background and Strategic Fit
• Customer Needs
• Assumptions
• Out of Scope (What we’re not doing)

Check out this example provided by Atlassian Agile Coach

Once you create your requirements, you’ll want to review with your development team for a level of effort (LOE). From there, you can approach management to allocate budget and resources.

In the coming weeks, I’ll cover the most common types of skill functionality requested by my enterprise clients.