.jpg)
Documenting conversational interactions is notoriously hard. Among people who design and build voice products and chatbots, this kind of conversation takes place all the time:
But documentation is a necessary evil. Teams (even small ones!) need documentation for many purposes — to think through problems, to generate focused discussion, to record how features should work, to share information across an organization, and to get stakeholder approval.
This post will give you some methods to try out, but you’ll get more value out of your documentation efforts if you pause for a beat and answer these questions:
- Purpose of the artifact: Why did you make this and what is it meant to communicate?
- Artifact user: Who’s seeing it? What do they get out of seeing it?
- Artifact feedback: What do you get from them seeing it? What kind of feedback (if any) is it meant to generate?
- Presentation time: How long do you have to show it? Is it for a 15 min overview or a 2 hour walk through?
- Longevity of artifact: How “permanent” is it? Is it a quick update or a long-lasting “source of truth”?
Taking the time to uncover the purpose of your artifacts (whether it’s a flow diagram, a slide deck, a chart, a demo video….) will prevent you from making documentation that no one uses. Believe us, spending a few hours on something your team ignores isn’t fun. We’ve been there.
So, here are some different techniques that conversation designers typically use. Some teams use all of them, and some teams use just a few. The underlying point here is, choose the documentation that works for your team. For better and for worse, there’s no universal method, and no standard set of tools, either!
TOOL #1: Sample Scripts
Sample scripts are like a little screenplay that captures a conversation between a person and a bot.
A sample script represents one single conversational pathway. Taking the time to think through one pathway at a time, turn by turn, helps you make dozens of little decisions. When you’re facing a blank slate, sample scripts are a terrific thinking tool. You’ll want to think about different tasks and contexts, and make dozens of these scripts.
Sample scripts have another incredible use: they can help your team understand the challenges of conversation design and raise fruitful questions that the team can align around. You can hold a sample scripting workshop where you invite your team to create sample scripts as a great starter for discussion.
TOOL #2: Flow Diagrams
Conversation designers use flow diagrams to capture what conversational pathways are supported. Flows help you think through these questions:
- What behaviors does each intent trigger?
- What system logic or user scenarios create different pathways?
- How many unique prompts are needed, and at which point in the conversation do they come up?
- Where into the )ow might a user enter, and how can they navigate from their entry point?
Depending on the purpose of the flow diagram, there are lots of different styles and approaches. For early-stage flow diagrams, we like to use a “sketchy” style to show key moments in the interaction, and how the conversations might branch. Keeping it sketchy and low-fi allows everyone to visually see that this is a work-in-progress.
Once you’ve got a clear sense of what the flows should account for, now’s a good time to get picky and spruce them up a bit. You want to account for everything in the formalized flows and compress the prompts and utterances down to 1-2 word labels (the actual prompts and utterances will be moved to a repository document for easier find and searching later, which, trust us, you’ll do a lot of).
Most conversation designers think in two levels: turn-by-turn, which is what you’ve seen so far, and then at a “zoomed-out” level, which considers the “phases” of an interaction. We call those phases “components.” Because you want users to be able to navigate intuitively, you can also diagram how a user would get from one component to the next, or go back.
These are also helpful when you’re further in the process to show your product and business stakeholders a more high-level view of what’s included in your experience.
TOOL #3: Storyboards
Sure, flows are great, but they can also be limited, and sometimes, you simply need a different method to think through the problem or show your team what’s on your mind. Storyboarding is one such great method. Basically, you divide a sequence of interactions into “frames” and give a visual representation for each step. The advantage is, they help you “zoom out” to consider the user in actual space and time. It’s great for multimodal interactions.
And lest you think you’re done, pull up a chair. There’s more! Here are a few examples:
Tables of training data:
Prompts Lists:
Charts to illustrate complexities:
TOOL #4: Prototyping
Prototypes are another important part of your documentation process. Flat, on-the-page artifacts can only go so far. Often, we hand off prototypes alongside other forms of documentation because showing is much clearer than telling. The benefits of adding prototypes to your practice overall include:
- Supplementing your documentation: it helps provide clarity in how what you’ve built should work
- Generating data: a prototype can help generate both usability and training data
- You can’t fix what you can’t “see”: a prototype can help you think through what’s actually happening in the experience more closely to what the user is experience and show others so you can discuss more thoroughly
There are so many ways to make zero-code prototypes. (Voiceflow is one of them!) Here are some other common methods. (We unpack all of these in our book, Conversations with Things.)
To end on a philosophical note, documentation is always a representation of an experience that plays out in the real world. No form of documentation has perfect fidelity to the final product, and any method has pros and cons. Tailor your deliverables to your team’s needs, and everyone will be much clearer and happier.
Some parting tips for creating useful documentation:
- Document everything. Even if you’re a team of one. You will forget, and you will be grateful for the bread crumb trail.
- Version it! Keep all your old documentation, label it, and make sure that it’s handy.
- Talk about it. Documentation is always just a representation of your ideas and always just a placeholder for conversation.
- Keep trying things. If your team isn’t pickin’ up what you’re puttin’ down, there’s always another way.
Happy documenting!
This post is adapted from Conversations with Things: UX Design for Chat and Voice, published by Rosenfeld Media in 2021. Now through June 12, 2021, you can get 20% off when you use this code, CWTTALK0521, at RM.com.
