When adding custom dialog, you should follow these best practices to ensure capsules are consistent with Bixby guidelines:
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
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...