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 topic in the Design Guides. You can also read the Dialog Affirmations for another example of good dialog practices.
General Best Practices
- Write Selection Prompts as questions instead of instructions or commands to the user.
Do: What kind of recipes are you looking for?
Don't Pick a recipe collection
- Instead of repeating the same question to users for a specific prompt, add variety.
Do: What are you in the mood for?; What kind of recipes would you like?; What are you craving?
Don't: What kinds of recipes would you like; What kinds of recipes would you like...
- Remove quotes, including single- and double-quotes with dialog fragments.
Do: Here are some Indian spinach recipes
Don't: Here are some 'Indian' "spinach" recipes.
- When conveying API or connection issues, use concise, simple messages that are in the first person without restating the intent.
Do: I’m having connection issues. Please try again later.
Don't: Unable to complete request for flight status of one-way flights on Delta from SFO to SJC on July 4th.
- Write short, direct Elicitation prompts without stating what is missing.
Do: How many people are you splitting the bill with?
Don't: In order to complete your 18% tip calculation on a total bill of $200 and split for your group, I need you to first tell me how many people are in your group.
- Use proper punctuation in dialog, with the exception of single-word responses, such as "20mph".
Do: It is going to be chilly outside!
Don't: It is going to be chilly outside
Hands-Free Dialog Best Practices
- 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 at12:45pm, the fourth one departs at 1:30pm, the fifth one departs at 3:20pm…
- Bixby should always be certain of what it does or doesn’t know, and what it can or cannot do. Eliminate uncertain words and phrases from dialog, even in error cases.
Do: I’m not able to do that yet.
Don't: Uh oh, turns out that I can’t do that.
- Avoid overly technical words and phrases to keep the conversation feeling natural and comfortable.
Do: I’m not able to do that yet.
Don't: That function is not currently supported.
- 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?
Event Dialog Best Practices
- 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 cooking in under 1 hour...
- When providing results with property projections, provide a simple answer instead of using full sentences.
Don't: The current ground speed for flight Delta 2049 from SFO to SJC on July 1st is 925 mph
- When providing results, use neutral language that doesn't identify sources.
Do: Here are some recipes for cakes.
Don't: I found some recipes on BigOven.com; here are the tastiest:
- Use confirmation prefix only when providing results.
Do: OK, here are some recipe ideas.
Don't: OK, I need more information from you.
- If no results are available, you can apologize on a limited basis, but overuse may come across as annoying or strange.
Do: I couldn't find recipes for Bombay duck.
Don't: Sorry, no recipes found for Bombay duck.
- When unable to provide the information requested by the user, it's sometimes helpful to provide some helpful related information instead of returning nothing to the user. However, make sure the replacement information is relevant and can possibly still be used.
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:
- Providing dialog commentary when results are unusual or surprising, but keep a positive tone. You can even use emojis if done in a tasteful way.
Do: Wow, this flight is usually late. Great! :)
Don't: Late again! Will they ever get it right?
- Add a colon (:) to dialog when introducing content.
Do: Here are some recipes:
Don't: Here are some recipes...