Update

.gitignore

@@ -135,7 +135,7 @@ venv.bak/
 .ropeproject
 
 # mkdocs documentation
-/site
+# /site
 
 # mypy
 .mypy_cache/

conversation-design/docs/capitalization-and-punctuation.md

@@ -0,0 +1,67 @@
+# Capitalization & punctuation
+
+Rules for display prompts, text in visuals, and chips.
+
+Capitalization
+
+Use sentence case (capitalizing only the first word of titles, headings, labels,
+and menu items). Research shows that sentence case is easier to scan than title
+case.
+
+Do.
+
+
+Don't.
+
+Contractions
+Use contractions. Messaging without contractions sounds stilted and robotic, rather than natural and conversational.
+
+Do.
+
+
+Don't.
+
+Commas
+Use the serial comma in a list of 3 or more items. Serial commas add clarity.
+
+Without the serial comma, individual items in your list may be incorrectly heard or read as groups (e.g., “daisies and sunflowers” sound like they come together, while “daisies, and sunflowers” are clearly separate).
+
+
+Do.
+
+
+Don't.
+
+Exclamation points
+Avoid exclamation points as they can be perceived as shouting.
+
+Do.
+
+Use common terminology that is familiar to most people (like "sign up as a member").
+
+
+Don't.
+
+Numerals
+Use numerals instead of text. Numerals make visual content more glanceable.
+
+Do.
+
+
+Don't.
+
+Symbols
+Use specialized symbols instead of text. Symbols make visual content more glanceable.
+
+Do.
+
+
+Don't.
+
+Time
+Use the format "AM" or "PM".
+
+Do.
+
+
+Don't.

conversation-design/docs/create-a-persona.md

@@ -0,0 +1,69 @@
+# Create a persona
+
+Think of your persona as the front end of your Action, that is, the conversational partner you create to interact directly with users. Defining a clear system persona is vital to ensuring a consistent user experience that builds user trust.
+Why use a persona?
+A persona is a design tool that helps you write conversations. Before you can write a dialog, you have to have a clear picture of who is communicating. A good persona evokes a distinct tone and personality, and it’s simple enough to keep top-of-mind when writing dialog. It should be easy to answer the question: “What would this persona say or do in this situation?”.
+
+Users will project a persona onto your Action whether you plan for one or not. So it's in your best interest to purposefully design the experience you want users to perceive, instead of leaving it up to chance.
+
+Note: The goal of creating a persona is not to trick the user into thinking they're talking to a human being, but simply to leverage the communication system users learned first and know best: conversation.
+How do I create a persona?
+Your persona can help provide users with a mental model for what your Action can do and how it works by starting with what users already know. For example, in a banking application, the persona could be modeled after an idealized bank teller—trustworthy with customers’ money and personal information. The metaphor of the bank teller makes this new experience feel familiar, since users’ real-world banking knowledge can guide them.
+Follow these steps to create your persona:
+Step 1	Brainstorm a list of adjectives (e.g., friendly, technologically competent). Focus on the qualities you want users to perceive when talking to your Action.
+Step 2	Narrow your list down to 4-6 key adjectives that describe your persona’s core personality traits.
+Step 3	Come up with a few different characters who embody these qualities (e.g., a barista, a fashion icon, a world traveler). Your persona doesn’t have to be a person. It could also be an anthropomorphized animal, an alien, an artificial intelligence, a cartoon character, etc.
+Step 4
+Choose one character that best embodies your Action and write a short description, no more than a paragraph. This description should provide a clear sense of what this persona is like, especially what it would say, write, or do.
+
+Focus on personality traits, and avoid specifying things like gender or age because they almost never critically define or differentiate a persona. Furthermore, deciding the gender upfront will make it harder to find the right voice, since you’ve already eliminated half of the options.
+
+Step 5	Find, or create, an image or two that visually represents your persona. Pictures are a great memory aid and can help you keep the persona in mind when writing dialog. If you create your own, consider using it as your Action’s logo so users can see it too.
+What voice should I choose?
+When people hear a voice, they instantly make assumptions about the speaker’s gender, age, social status, emotional state, and place of origin, as well as personality traits like warmth, confidence, intelligence, etc. People can’t help but do this with virtual assistants, too—so guide the assumptions they make about your Action by choosing a voice that is consistent with your persona.
+There are 2 types of voices:
+Type	Description	Pros	Cons
+Synthesized	The Actions on Google platform provides a variety of text-to-speech (TTS) voices that speak different languages. Go to Languages and Locales to hear them. Note that you can adjust the way the synthesized speech sounds by using Speech Synthesis Markup Language (SSML). For example, you may want to add silence or pauses, specify how numbers should be read, or adjust the intonation.
+Hear prompts as soon as you’ve written them
+Make quick and easy edits
+Localization is built-in
+Can sound unnatural or robotic
+Less expressive. Difficult to convey humor, sarcasm, etc.
+Few voices to choose from
+Recorded	You can hire a professional voice actor, or even try using your own voice. Either way, you’ll need to record all the audio that will be used in your Action.
+Natural and human
+Very expressive. Can convey humor, sarcasm, etc.
+Unlimited voices to choose from
+Edits require re-recording
+Recordings have to be localized
+Requires robust management system for audio files
+Choose the best voice for your persona by holding an audition.
+Step 1	Write a few spoken prompts that your persona would say. Or better yet, write a sample dialog. These will be the lines used for the audition.
+Step 2
+If you’re auditioning TTS voices, render your lines in each voice.
+
+If you’re auditioning voice actors, tell them about what your Action does and give them your persona description and key adjectives so they understand the character they’re embodying. Then record them reading the lines.
+
+Step 3	Create a scorecard using the key adjectives that describe your persona. The goal is to rate how well a voice conveys each adjective using a 5-point scale, with 1 meaning “not very well” and 5 meaning “very well."
+Step 4
+Organize a listening party with your friends or colleagues. Audition each voice and rate them on the scorecard. Focus on the voice by just listening—don’t read along. It helps to close your eyes and try to imagine the speaker.
+
+Step 5	Review the ratings and choose the winner! If there’s a tie, listen to the voices again, this time rating them against your short persona description.
+Examples
+Here’s an example of the persona created for the Google I/O 18 Action:
+Key Adjectives
+Practical/straightforward
+Techie
+Enthusiastic
+I/O expert
+Characters who embody those adjectives
+Who would be an I/O expert?
+
+I/O Planning Committee member
+Speaker at I/O
+Google Developer Expert
+Google Developer Group organizer
+Frequent I/O attendee
+Short description	The Keeper of I/O-Specific Knowledge is a Google Developer Expert who believes strongly in the power of technology. A skilled networker, they spend their time answering questions on StackOverflow, building apps for big brands, and helping Google run madewithcode.com. They’ve attended I/O for the past 7 years and are a trusted member of the developer community. As a spokesperson for I/O, they take this responsibility very seriously, but, of course, they’re still going to have fun doing it.
+Voice chosen	Of the available TTS voices for United States English, Female 2 ranked highest on practical/straightforward and techie
+Check out this two-part blog post for more details on how we designed and built the I/O 18 Action. You can also view the open-source code for a closer look at the structure.

conversation-design/docs/design-for-the-long-tail.md

@@ -0,0 +1,64 @@
+# Design for the long tail
+
+By now you should have a design that covers the well-worn paths most users will follow. Now it’s time to focus on the long tail of paths that remain. Think about all the things that can go wrong in your conversation and all the unexpected or unsupported paths users might take.
+Don't overdesign
+
+In the requirements phase, you defined a clear set of key use cases. Keep these priorities in mind and avoid adding edge cases to this list. As you get into the details of the design, new scenarios will come up that you hadn’t considered. Before expanding the scope of the design to handle these new scenarios, carefully consider the impact.
+
+The head	The body	The long tail
+Key use cases
+
+These are the most important and most common conversational paths that users will take through your feature. Focus the majority of your effort on making these paths a great user experience.
+
+Detours
+
+These are less common, and often less direct or less successful, conversational paths through your feature. Take the time to adequately support them, but avoid spending too much time and effort designing them.
+
+Edge cases
+
+These are highly uncommon paths. Consider whether generic prompts like “Sorry I’m not sure how to help” are good enough, or if you can be a little more specific with a similar minimally viable solution.
+
+Use the 80/20 rule, or Pareto Principle, to avoid overdesigning.
+For conversation design, this rule is a way of saying that not all paths are created equal. 80% of users follow the most common 20% of possible paths in a dialog. Therefore, invest resources accordingly for the biggest impact.
+
+Similarly, there are trade-offs in terms of perfection or completeness. It may take 80% of the work to really polish the last 20% of the project. In these cases, the unpolished effort may be "good enough."
+
+
+Common detours
+In between key use cases and edge cases are a number of somewhat common detours. Usually, these are new scenarios that you hadn’t considered until they were revealed during testing or discovered during development. And most of the time, they require longer, less direct handling down an alternative path.
+
+Here’s a couple of common detours to consider:
+
+Unlinked accounts
+Users may have to link accounts or devices (e.g. home automation) before they can use certain features.
+
+In this case, the user has not linked their account.
+
+Unsupported actions
+Your Action might not be able to support some common user requests.
+
+Users may ask for actions that your Action can’t support.
+
+Intent coverage
+Conversation design involves scripting one half of a dialog, hoping it’s robust enough that anyone can step in and act out the other half. When designing for the long tail, focus on what the user could say at every step in your dialog to define your intents (also called grammars).
+
+An intent represents a mapping between what a user says and what your Action should do as a result. For example, the prompt “Do you like pizza?” requires intents for “yes” and “no”. Each intent should have a variety of training phrases associated with it, including synonyms like “yeah” and “nope” as well as variations like “I love it” or “It’s gross.” These may be weighted by how frequently they occur. Intents can also include annotation, for example, categorizing “fresh mozzarella” as a pizza topping in the user response “only if it’s made with fresh mozzarella.”
+
+If you’re using Dialogflow, go here to read more about intents.
+
+Preventing errors from occurring is better than handling errors after they occur.
+Your persona won't always be able to handle cooperative responses. In these cases, rely on lightweight and conversational error handling to get the dialog back on track in a way that doesn't draw attention to the error.
+
+Do.
+
+Include a “done” intent with training phrases like “I’m done” or “that’s all."
+
+
+Don't.
+
+If the Action is only expecting questions about I/O, the user’s response will trigger a No Match error.
+
+Error handling
+Even with robust intents, there is still room for error. Users may go off script by remaining silent (a No Input error) or saying something unexpected (a No Match error). Use error prompts to gently steer users back towards successful paths or reset their expectations about what is and isn’t possible.
+
+Good error handling is context-specific, so prompts for No Input and No Match errors must be designed for every turn in the dialog.

conversation-design/docs/gather-requirements.md

@@ -0,0 +1,99 @@
+# Gather requirements
+
+Gathering requirements for a conversational experience is not just about defining features and functionality, though that is the main outcome. At its core, the requirements-gathering process is about understanding users and technical capabilities.
+
+Starting with clear, well-researched requirements is the best way to avoid the need for major changes after design and/or development is completed.
+
+Identify your users
+Gathering requirements is all about asking questions and using data to answer them. For example:
+
+Who are your users?
+What are their needs?
+How are they completing these tasks today?
+What words and phrases do they use to talk about these tasks?
+What situations or circumstances trigger these tasks?
+Accommodate all users
+While it’s important to optimize for your most frequent users, don’t do so at the expense of other users’ experiences. A well-designed product is inclusive and universally accessible. Designing for different populations means leveraging inclusive design or universal design strategies. Often, the accommodation you’re forced to make for one population ends up benefiting everyone (e.g., a ramp is easier than stairs). For more information, see the Material Design guidelines for Accessibility.
+
+Create user personas and journeys
+User persona
+Who is the user?
+
+A user persona is a specific but brief description of an individual user. Think about the types of people you expect to use your Actions, and create a few user personas to represent them. These user personas will help you avoid designing only for yourself and your goals.
+User journeys
+What are the user’s goals?
+
+What’s the user’s context?
+
+A user journey is the pathway for the user to complete a goal in a given context.
+Critical user journeys
+Describe each of the relevant moments in the journey
+
+Critical user journeys are those that either 1) happen very often or 2) are of key importance to the user. Aim to help users to complete one of these journeys from start to finish. Focusing on these will help you build Actions that reach a large and/or dedicated audience.
+Example from the Google I/O 18 Action
+Check out these blog posts for more details on how we designed and built the I/O 18 Action. You can also see the open-source code for a deeper look into the structure.
+Who is the user?
+Anna, 27, is a UX designer and sketch artist with a passion for creating engaging user experiences that help users get things done in their lives.
+
+What are the user’s goals?
+Anna’s got a full schedule planned for Google I/O and doesn’t want to miss a thing. She’s excited to learn about how to design an experience with Actions on Google by attending relevant talks. She also wants to check out all the new demos and pick up some Google swag.
+
+What’s the user’s context?
+Anna is in Mountain View for Google I/O. She’s just starting her day, leaving her hotel and heading to Shoreline Amphitheatre.
+
+Describe each of the relevant moments in the journey.
+Anna starts by getting directions to Shoreline Amphitheatre and info on where to park. Once at the venue, she gets help finding her way to badge pickup. Afterwards, she heads to the main stage for the keynote, grabbing something for breakfast on the way. Once settled, she’s got some time to wait, so she reviews her next few sessions. It’s going to be a sunny day, so she’s reminded to use the sunscreen in her swag bag while she waits.
+
+Identify technical capabilities
+Determine what is and isn’t possible given your timeline and resources.
+Systems
+What are the capabilities and limitations of the various systems that your Actions will rely on?
+
+Example: Google I/O 18 allows users to create a personalized schedule of all the sessions they want to attend
+How will users be identified? Across sessions?
+How and where will their progress be saved?
+Will their changes sync with the Google I/O mobile app?
+How will you handle overlapping sessions?
+Data
+What’s the format and quality of any data you’ll be using?
+
+Example: Google I/O 18 reads information about the sessions
+What information is available? (e.g., titles, descriptions, dates & times, topics)
+What’s the format of the session information? Is it plain text, audio, or other?
+If the content is plain text, was it written to be seen or to be heard?
+How long is it? Or how long does it take to read?
+Often, some reformatting needs to happen before some types of content can be appropriately rendered in text-to-speech (TTS).
+
+Identify your key use cases
+Considering technical limitations, level of effort, and timeline, what use cases can you support? Assign priorities accordingly.
+Aim for impact.
+Put your effort where it will have the most impact. This may be scenarios that affect the largest number of users. It could be highly visible use cases/market differentiators. Or it may be a feature that makes a big difference for a handful of loyal power users.
+What are users asking for?
+Do some user research on how users complete this task today and the language they use to describe it.
+Example from the Google I/O 18 Action:
+If you haven’t already, be sure to read these blog posts for a deep dive on how we designed and built the I/O 18 Action (or take a look at the code).
+
+For the Google I/O 18 Action, we talked with Googlers who’ve worked at the event in previous years. We asked them what kinds of questions attendees usually have during the event. These questions typically fell within one of these 4 categories:
+
+General navigation	Personal navigation	Event details	Location-specific event details
+“Where’s the bathroom?”
+
+“Where are the codelabs?”
+
+“Where’s my next session?”
+
+“Where can I get my app reviewed?”
+
+“What time is lunch?”
+
+“When’s the after party?”
+
+“What’s the next session in this room?”
+
+“What can I do here?”
+
+With that knowledge, we decided to focus on these key use cases:
+
+Provide wayfinding information for locations specific to Shoreline Amphitheatre, for example: bathrooms, parking, driving directions
+Provide wayfinding information for locations specific to Google I/O, for example: badge pickup, sandbox, codelabs, office hours and app reviews, after hours, I/O store
+Provide event details for all keynotes, sessions, office hours, and meals; allow them to be filtered by time, location, or the user’s schedule