Dialog Best Practices
When adding custom dialog, you should follow these best practices to ensure capsules are consistent with Bixby guidelines.
These best practices are in addition to the general guidelines you should follow in the Writing Dialog Design Guide. You can also read the Dialog Affirmations for another example of good dialog practices.
General Best Practices
Rather than blame the user for errors, allow Bixby to take blame or state something isn't available.
Do: There aren't any restaurants with that name.
Don't: I don't understand the name you gave.
Do not command the user on how they should talk to Bixby. Tell them what Bixby can do for them.
Do: I can get you to your destination. Where are you headed?
Don't: Tell me where to navigate.
Say or display the most important information first without extraneous information or sources.
Do: I found several chocolate cake recipes. Want me to read the most popular result?
Don't: I found chocolate cake recipes from BigOven.com, Food Network, and more. Which one?
Avoid technical jargon and abbreviations. Instead, explain using generic, well-known terms.
Do: There are issues loading Weather. Let me try again.
Don't: To connect to the capsule's API, I need to run a query first.
Results and Progress Events
When creating dialog for progress events, use short sentences that focus on the top-level goal.
Do: Finding recipes…
Don't: Finding vegan Mexican recipes for 4 people that can be cooked in under 1 hour…
Alternate between confirmation prefixes when providing results.
Do: All right, here are some recipe ideas. (followed by) Got it. Here are… (followed by) Okay, here are…
Don't: always say Okay, here are some recipe ideas.
When providing results with property projections, provide a simple answer instead of using full sentences.
Do: 925 mph
Don't: The current ground speed for flight Delta 2049 from SFO to SJC on July 1st is 925 mph
Add a colon (:) to dialog when introducing results.
Do: Here are some recipes:
Don't: Here are some recipes…
You can provide dialog commentary when results are unusual or surprising, but keep a positive tone.
Do: Wow, this flight is usually late. Great! :)
Don't: Late again! Will they ever get it right?
You can apologize on a limited basis if no results are available, but it's best to try to offer alternatives.
Do: I couldn't find recipes for Bombay Duck. Want to try a new search?
Don't: Sorry, I can't find recipes for Bombay Duck.
If your capsule can't provide the information requested by the user, you can provide similar results rather than returning nothing if the information is relevant to the request.
Do: I couldn't find a flight bearing for Delta 2049. Here's the flight position:
Don't: I couldn't find the air quality index for Los Angeles, CA. Instead, here is the index for Oslo, Norway:
Be clear when Bixby can't find information or doesn't have the ability to fulfill a request. Don't use uncertain words and phrases in dialog.
Do: I'm not able to do that yet.
Don't: Uh oh, I don't think I can do that.
Prompts
Prompts are questions or acknowledgements during a conversation that signal a turn, a point where either Bixby or the user stops talking and the other starts. As mentioned in the General section, it is vital to provide the most important, relevant information to the user first. Prompts, however, are the most actionable items and like all "call to actions" should be placed at the end of dialog.
Place prompt questions at the end of the dialog. This way, a user won't start talking while Bixby is still asking or explaining.
Do: Katie said "Hello." Want to reply?
Don't: Want to reply to Katie? She said "Hello".
Ask for one piece of information at a time.
Do: What time is this event?
Don't: What time is the event, where is it and who is attending?
When preference learning is available, it is helpful to provide suggestions.
Do: Spotify is the most popular option. Want to use that?
Don't: You've selected Spotify, Pandora, and Radio before. Which one?
During confirmations, repeat back what the user said to make sure Bixby heard correctly.
Do: Okay, reservation for 2 people at Morton's The Steakhouse in San Jose tomorrow at 7:00pm. Ready to book it?
Don't: Reservation confirmed.
Reprompting
If Bixby doesn't understand what the user says (either the user doesn't say anything or says something that is not matched to an intent), let the user know instead before reprompting. Typically Bixby prompts the user up to 3 times before ending the conversation.
Explain the situation or orient the user during the first reprompt.
Do: I can't find that person. Who do you want to call?
Don't: Who do you want to call? (continuously repeats)
After re-prompting a user more than once, provide an example utterance.
Do: You can say "next" or "go back." Which would you like?
Don't: What do you want to do?
Display vs. Spoken Dialog
Just as people speak differently in writing than in speech, Bixby is the same. On handheld devices, display dialog will usually show views (of results) and call to actions (typically with buttons or conversation drivers) while spoken dialog will provide full sentences and questions.
When designing for devices that can speak text aloud (such as using a mobile phone with headphones), assume that the user is not looking at the screen, even if the device has one. This will give you an idea of how much information Bixby should speak aloud rather than only display on-screen.
Spoken Dialog
Include all important information in the spoken dialog. Do not assume the user can look at the screen at all.
Do: Okay, reservation for 2 people at Applebee's in San Jose tomorrow at 7:00pm. Ready to book it?
Don't: Ready to book your reservation?
Avoid overwhelming users with too many pieces of information at once. Remember, they're only listening to this, and will have to remember it all. If Bixby needs to read a long list, break it up into Read 1 or Read 3 scenarios.
Do: There are 9 flights from San Diego to San Jose today. The first 3 depart at 10:15am, 11:30am and 12:45pm. Do any of those sound good?
Don't: There are 9 flights from San Diego to San Jose today. The first one departs at 10:15am, the second one departs at 11:30am, the third one departs at 12:45pm, the fourth one departs at 1:30pm, the fifth one departs at 3:20pm…
Displayed Dialog
Keep display dialog minimal, since the user is listening to the spoken dialog. Display dialog is meant to complement the design, not to stand on its own. In hands-free mode, assume that the user is not looking at the screen.
Do: Ready to book it?
Don't: Okay, your reservation for 2 people for Taylor Swift at Madison Square Garden on Thursday, October 24, 2019 comes to $254.37. Are you ready to confirm your reservation?