Bixby Developer Center

Now that you've had a chance to start learning about how to create capsules in the quick start guide, you can begin planning your own capsule! This guide is meant to be a set of recommendations that you should think about and plan ahead of time before creating your capsules.

Specifically, it teaches you how to do sufficient research for your capsule, write out specifications, and then plan the engineering work involved.

Research Phase

While you're creating your own capsule, narrow down what you want the user to be able to accomplish through Bixby while using their device and the cloud platform. Essentially, you're asking "What ability do I want to teach Bixby?"

In order to answer this question, consider the following:

• Understand your target users. Figure out the prioritization of user goals, and consequently, what Bixby will do for your users. For example, if you're building a weather capsule and the user asks "What's the weather like today?", they probably want to know the current temperature and then the weather conditions (for example, if it's raining), in that order.
• Understand your market, and specifically the domain within it. For example, if you're building a capsule to check stock market prices, it is useful to have expertise in finance and various stock markets. If you're building this capsule for users located in the US, you might want to be familiar with the Dow Jones Industrial Average and the S&P 500.
• Decide which locales you want to support. This is going to affect how you organize your resources during development. The specific list of supported languages are determined when you prepare your targets.

Specification Phase

After you've researched enough information for your capsule, you can start your specification phase:

1. Start writing user stories.
2. Then, create a more complete list of use cases.
3. Begin listing inputs and outputs that your capsule will need.
4. At the very least, consider creating a must-work utterances table to establish a base minimum for how your capsule should work.

Write User Scenarios

Writing typical user scenarios enables you to really narrow down the scope of what your capsule will be used for by users. User scenarios also help you understand what to expect from Bixby. Specifically, these user scenarios will be useful later, when you start adding stories and training examples.

Here are some recommendations for writing a good scenario:

• Do limit each scenario to a single paragraph that focuses on a single usage case.
• Do make it memorable by adding names, jobs, activities, and places.
• Do ensure that it's realistic, believable, and representative of a typical user experience.
• Do make sure your scenarios have a diversity of people, usages, and context.
• Do write at least 2 user scenarios per capsule, which will help keep your capsule focused.
• Do keep your capsule as tightly scoped as possible.
• Don't worry too much about utterances that are outside of your capsule's scope!

The following examples are well-written user scenarios:

Example Scenario 1: Flight Status Capsule

Friend on Flight

Jane is picking up her roommate, Delilah, who is arriving at San Francisco Airport on a flight from Sydney, Australia. She wants to know if the flight is on time and what terminal and gate it arrives at. Before driving to the airport, she checks her phone assistant for details on "the BA flight from Sydney to SFO this afternoon" and realizes it left 45 minutes late. Instead of waiting in the parking lot, she uses the extra time to pick up coffee from Blue Bottle in SF (Delilah's favorite), to help cheer up her friend on arrival after a long and delayed journey. BFF #win.

Example Scenario 2: Recipe Capsule

Specific Ingredients

Raj arrives home after a long day of work and is immediately greeted at the door by his children. His stomach growls, and he checks the fridge. He notices an assortment of products and leftovers, as well as a large chicken. He pulls out his phone and with one hand asks: "What recipes can I make with chicken, tomato, and mozzarella cheese?" and selects the second option (which looks delicious). Following the steps in the recipe, he is able to prepare a great chicken dinner for his family.

Example Scenario 3: Weather Capsule

Individual Local

Jae lives in Suwon and likes to dress comfortably. He wakes up in the morning and checks notifications on his phone, and then he asks his assistant a few questions about the weather. He asks what the temperature will be today for his current location. He then asks what the chances are of rain at 6:00 pm when he gets off work and walks to the train station. Good news! It will be warm and sunny with only a 1% chance of rain. So, he decides to wear his favorite cotton T-shirt and khakis with open-toed sandals. 봄 햇살이 가득한 화창한 하루네요! ("Bom haes-sal-i gadeughan hwachanghan haluneyo"—or "Fine day full of Spring-like sunshine!")

List Use Cases

While user scenarios give you specific details on how a user will interact with your capsule, listing use cases helps you define scope for your capsule. It also gives you some idea of which actions you will need to implement.

Here are some best practices for writing a use cases list:

• Do cover every distinct way of using the capsule.
• Do include an example utterance.
• Do rank and prioritize the list (for example: P1, P2, P3).
• Do capture all feature ideas. It's okay to mark some as "postponed".
• Do capture every unique feature and ensure diversity in the examples.
• Don't try to capture every single possible variation! For example, if you have "What is the current price of TGT?", then you don't also need "What is the current price of AAPL?" and "What is the current price of ORCL?"

In general, a simple capsule should have about 5 use cases, while a more advanced capsule should have about 15.

Example Use Case Table - Simple Stocks Capsule

Inputs and Outputs

Once you have your scenarios listed, it's important to understand what Bixby will need (inputs) in order to produce the desired results (outputs). Creating an input table and an output table helps keep track of the various concept models your capsule needs.

Example Input and Output Table - Simple Stocks Capsule

Must-Work Utterances

A must-work utterances (MWU) table helps you keep track of use cases to support through utterance examples with input mapping. Use a simple table with structures, and leverage your existing inputs table. MWU tables are normally created by a product manager, but can be used by your developers, designers, and quality assurance engineers. You might also want to keep track of capsule versions, with future work being put on separate tables. Make sure you also test variations, while limiting duplicate testing.

Example MWU Table - Simple Stocks Capsule

Engineering Planning Phase

This section discusses the mechanics of creating your capsule, preferably after you've finished researching information and creating specifications. First, you'll need to plan API integration. Then you can further familiarize yourself with Bixby's platform, using the Developers' Guides.

Plan API Integration

Since you are likely going to be using an existing API to implement actions, you should remember that Bixby is a conversational user interface (CUI):

• Don't just recreate an app in a capsule.
• Don't design your capsule strictly based on your existing API.

Capsule Developer Workflow

For more information on the steps a capsule developer should take to actually create a capsule, see the Capsule Developer Workflow Developers' Guide.