Hi wonderful people!
In today’s post, I want to talk about how to document voice interaction – whether it’s Alexa or Google Home…or just about anything that has to do with voice.
The current popular way
The current way a lot of developers tend to document voice interactions include:
- Not documenting at all (bad choice)
- Documentation based on just flow-chart or call-flow (uh no!)
The proper way includes:
- Sample dialogs demonstrating use cases
- A state-by-state design for documentation
Let’s take a sample Alexa skill for example:
User: Alexa – open GameSpot and check the price of [Little Nightmares]
Alexa: Sure – now is that for PS4 or XBOX One?
User: It’s for X-box One
Alexa: Little Nightmare for X-box One is available for $49.99. Just so you know – you can pick up a copy at your nearest store – located at 478 Colonial Drive. Would you like to hear that again?
User: No thanks
So let’s just stop there. How do we document this? What I demonstrated above is called a sample dialog and the purpose is to show a use case. In voice we don’t have wire-frames so it’s important to have a sample dialog for your major use cases or scenarios.
The next part is state-by-state documentation. What this means is to understand that every Alexa skill follows a set of logic conditions. Therefore it is important to document and map this out. If we do this properly, developers and design can clearly understand the process behind the skill.
State Type – Presentation
State Name – Main Menu
Alexa: Welcome to GameSpot – what can I do for you? You can say – check the price, find the nearest store or product availability.
User Entry -> Go to next state
Failure -> Go to FailureState
Example of a FailureState:
State Type – Transfer
State Name – FailureState
Alexa: Sorry – I’m having trouble accessing this skill. Please try again.
A visual demo: