How to document conversation designs

The role of Conversation Designer comes with some unique challenges - but the biggest of all is documentation. At Voiceflow, we get the chance to speak with a lot of designers and their teams about their process, and documentation comes up consistently as one of the major pain points they have with their work.

As with all design roles, the documentation of work is a hugely important part of the job. From research to logging sample dialogues, happy paths, and more – we rely on documentation to effectively communicate our designs with our team, stakeholders, and users.

We lack a standard conversation design artifact

Unlike other product disciplines, there isn't a core artifact that acts as a single output.

  • UX Designers create mockups
  • UX Researchers create Research Summaries
  • Content Managers create copy decks
  • PMs create product requirement docs

And more than other design disciplines, conversation design seems to have more unique outputs for the work that needs to be communicated through documentation:

  • Content - outlining expected interactions from a user and how the system will respond
  • User experience - defining the flow of these interactions
  • Situations - how the different potential user contexts will impact the above
  • Emotion, Tone, and Voice - how all the content is delivered to the end-user
  • Functionality - how this experience interacts with systems and services

A conversation designer's job is to create the best possible solution that pulls all of these outputs into a cohesive experience.

Because the best way to communicate response content is not the best way to communicate a user experience flow, it is tough to make a tangible end-to-end conversation design solution.

This causes a significant pain point around miscommunication with teammates - wasting time manually filling the gaps between what your documentation can convey, or even worse, resulting in an end product that doesn't match the design.

There are a few reasons we can point to why this might be the case:


Conversation design is a multi-functional role. This is obvious when you see the different backgrounds of the majority of people working in Conversation Design roles today: Linguistics, UX Design, Development, Copywriting, Research, and Academia. Because of this, the output of our work is fragmented across all these functions.

Fragmented Tools

For each function of the role, we'll employ a different tool to do each of those jobs the best. Most tools used are general-purpose office, design, or developments that get shoehorned into the use cases needed for conversation designers.

Because the standards for conversation designers are still being formed, there are few purpose-built tools for the profession. Even Voiceflow was not focused on solving this problem when launched, so we have to iterate and evolve the product in this direction.

Smaller Seats

Within the larger team that is focused on build conversational experiences, the conversation designer is just a small part of that. We often are working with many more designers, developers, copywriters, and product folks.

That means we have a smaller seat at the table in the makeup of the typical product team, so we end up defaulting to the preferences and tooling of our teammates and stakeholders.

The purpose of conversation design documentation

As the community of conversation designers shares best practices about how they document their work, the ideal artifact tends to play three critical roles:

Single source of truth

It's more work to keep information up-to-date across multiple sources, and as soon as documentation get out-of-date, teammates will stop trusting it. If your teammates can't trust your documentation to be the source-of-truth for your project, then it serves no purpose.

It's tough to get a complete picture of a design when the interaction model, response content, visuals, and situation designs all live in different places. It's not a tangible way to interact with those designs.

Conversation designers need a single source of truth for their end-to-end design.

A living document

The output of a conversation designer comes in many forms throughout a project, and your design documentation needs to communicate these all formats equally well. It should work at all phases in your project lifecycle - from very early-stage dialogue samples to late-stage end-to-end user flows.

Having documentation that evolves throughout a project allows you to communicate the design decisions made along the way, and why they were made. Your team can only trust your design decisions if they understand how you arrived at them, so you want to 'show your work' in your documentation, not the end output.


Conversation design is tricky to describe to your team, customers, and stakeholders. It's an even harder thing for them to try to envision. So, the only real way to communicate a conversation design to make it tangible and interactive.

As designers, we want to get as much feedback as possible throughout your design process to challenge our ideas and layer in others' ideas, which will ultimately strengthen our solution.

A lot of the documentation we rely on has little interactivity and does a poor job of communicating designs, so we never really get feedback. Our work suffers as a result.

The prototype is the primary conversation design artifact

(At least, this is the bet we're making at Voiceflow...)

There is no perfect solution for conversation design documentation currently. Still, more and more, we see conversation designers coalescing around the conversation prototype as the primary artifact they use to document and communicate their designs.

insurance assistant workflow image

It's multi-functional

As a functional tool for conversation designers, a prototype can encapsulate all of the outputs from your work - response content, integration requirements, NLU training data, UX designs, user flows, situation, and context.

The additional benefit of this is that each piece of content gains additional context when viewed s part of an end-to-end experience.

For example:
When your copywriter needs to review your response content, reviewing it in an Excel document provides no context for where, when, and how a user hears that response. That context is so vital for them to best craft the copy, and a prototype allows them to do just that.

It's constantly evolving

A prototype can act as a tool to communicate your solution at any stage in your product lifecycle. Each step in the conversation design process adds a layer onto the solution, making it a bit more fully-featured:

  • Sample dialogues map out your core solution concepts
  • Interaction model design defines the core actions required for that concept
  • Happy path design turns those core actions into an end-to-end flow
  • Repair, error and unhappy path designs builds all edge cases into an end-to-end flow
  • Situation design applies that end-to-end flow to all situations of use
  • Technical and Visual requirements turn that into a fully interactive, multi-modal flow

Prototypes allow you to communicate the output at each step along the way, and most importantly, at each step...

It's tangible and accessible

Conversation Design is a team sport. Our work as conversation designers alone doesn't result in much without developers, UX Designers, PMs, copywriters, linguists, UX Researchers, and yes, even stakeholders.

As a communication tool, a prototype helps your team view the designed experience through your users' eyes.

As a feedback mechanism, a prototype allows designers to receive more insightful, contextual feedback from your team and users.

Good conversation design documentation = good conversation design

Prototyping isn't just a step in your process; it's an artifact that evolves each step of the way. This will open up the opportunity for feedback and research as you go.

Conversation design is a primarily non-visual experience, but prototyping your conversation can make it tangible for stakeholder feedback and customer research. And in the end, better documentation will allow for better handoff and ensure that the conversations in your design are the conversations that get built.

If you'd like to learn more about documenting conversation designs, check out our online community or our YouTube channel.