Managing Versions and Changes

Documentation and changelog practices in the conversation design field vary from team to team and have no industry standard. Developer notes are stored in Jira, product stakeholder comments are in Figma, conversation logic is in Mira and Voiceflow, and so, the details of the assistant are unnecessarily spread between multiple platforms. 

Effective markup and versioning capabilities enhances communication and collaboration among designers and stakeholders, by providing a clear and accessible record of design decisions, revisions, and progress. This can help to minimize confusion and misunderstandings, and can facilitate more effective decision-making and problem-solving.

Voiceflow is designed such that:

• collaborative feedback is located all within the assistant canvas as a single source of truth
• product versioning is 1. differentiated between testing and productive environments 2. recorded so that changes can be rolled back. 

Documentation Practices in Voiceflow

To encourage each team to utilize Voiceflow to the fullest extent with team members, Voiceflow has extensive product support for Canvas Markup, allowing members to start comment threads, add text and images to the canvas, and run effective design reviews. Features like Custom Actions also give designers the opportunity to better define assistant functions that require development efforts. 

Changelog Practices

When a team works together on a single assistant, it can become complicated to keep track of the most recent changes and whether a domain is still in design mode or ready for review and production. 

Domain View

After clicking on an assistant in your workspace dashboard (and avoiding the Designer button), you will be allowed to oversee the different domains of an assistant and whether they are flagged as still being designed, in review phase, or planned to be in production. You can also see when the domain was last modified, and whether anyone is currently on the same assistant canvas as you. 

Version Control

When an assistant has been published, the state at which the assistant was saved and published is forever preserved in the Versions tab of an assistant's settings page.

• By publishing your assistant, you can ensure that changes made to the assistant on the design canvas are not automatically populated in production until a new version is made.
• If the current version were to experience technical issues, changes can be easily rolled back by reverting to a previous version.