Best Practices for Building and Maintaining a Chatbot
Building and maintaining a chatbot requires development discipline to maximize quality. A chatbot is ultimately a code artifact and needs to be treated and handled as such. This article lays out several techniques and processes for ensuring your chatbot is as good as it can be. These techniques are split across three focus areas: change management practices, automation practices, and coding convention practices.
Change management practices
The best change management practices from traditional software development still apply to chat bots. The three practices below can work independently but are strongest when you combine them together!
Source Code Management
Use a source code management (SCM) system like Git to version your code. Watson Assistant has an export workspace API that lets you save a workspace as a JSON file. (Be sure to use the export=true and sort=stable parameters.) This JSON file can be stored in any SCM system.
Small, frequent commits to an SCM system build a trackable history for the evolution of the bot’s source code. While the Watson Assistant code is stored in a JSON structure, a ‘diff’ between code versions will identify the number and nature of changes between versions. This is invaluable both for debugging errors and for rolling back changes to a previous state. Note that by using the Watson Assistant update workspace API with a workspace JSON file you can roll back the bot to any version you have in your history.
The following can be used as the basis of a backup script.
curl -u "apikey:$APIKEY" "$URL/v1/workspaces/$WORKSPACEID?version=2018–09–20&export=true&include_audit=false&sort=stable" -o my_workspace.jsongit add my_workspace.jsongit commit -m "$MESSAGE"git push
Be sure to version the bot code in SCM after each discrete unit of work is completed. (Caveat: the cited API can only be called 30 times in one half hour.)
Change Records
Use a change record tracking system to track tasks, defects, and feature requests. Any tracking system will do, but you should favor an instantly shareable online repository (ala Git issues) rather than a local file (ala Excel spreadsheet). You don’t want to be emailing change records around!
Further, be sure to link code changes to change records, minimally through the commit message. For example, Git commits and issues can be linked automatically through a specially formatted commit message. If you are working on Issue #53, just include “#53” anywhere in the commit message. Check the documentation for your specific SCM and issue tracking system.
Additionally, change records and tags/branches should be created for significant deployments (ie releases to higher environments or production). The following article lays out a Git branching strategy that helps you keep track of which versions of your code exist in which environments. See A Version Control Strategy for AI Applications for more.
Pair Programming
Pair programming ensures that multiple people are looking at code before it is delivered. “Two heads are better than one” applies to chat bots too! Pair programming can be done at multiple points in the chatbot writing process.
First, the chatbot can be written as a true pair programming exercise. Two chatbot developers work together — one at the keyboard, one watching/advising — providing the tightest possible feedback loop on new code being written. Second, any code changes (versioned in SCM and linked to change records!) can be reviewed through a Code Review process.
Each method has benefits and drawbacks. Code Review takes less time than true pair programming but has a slower feedback cycle. Whichever method you choose, you are sure to squash more problems earlier in the process if you have multiple eyes looking at the code going into the system.
Automation practices
Automate as much as you can! Removing manual steps and manual tests where possible speeds up your development process and increases quality. As with the previous section, these practices can be implemented independently but become even more powerful when combined, especially in a Continuous Integration and Deployment pipeline.
Automated testing
Both the classifier logic and the dialog logic of a chatbot can and should be regularly tested. Check out the Testing Strategies for Chatbots guide: Part 1 — Testing Their Classifiers and Part 2 — Testing Their Dialog Logic for more information. Even better, tie any failed tests (and eventual fixes) through Change Records and SCM as described above.
Automated testing becomes more important the more test cases you have. Don’t spend time manually regression testing your chatbot — automate as many regression tests as you can.
Detailed syntax validation
Watson Assistant will automatically verify that your entire workspace and individual chat nodes contain valid JSON. That verification will not check if you are following syntax patterns for systems that you are interacting with or that you are following any coding guidelines (more on coding guidelines later). For instance, voice chatbots using IBM Voice Gateway need to provide very specific JSON structures that Watson Assistant does not know how to validate. Watson Assistant Syntax Validation for Voice Gateway and SOE Integration includes common syntax patterns that need to be validated in chat bots with integration code. Use the validation logic in the attached code to validate your own chatbot or extend the validation logic with your specific requirements.
Automated deployments
Combine the practices above to automatically validate a chatbot, then to store its updated code in SCM and deploy it to higher environments when validation passes. Spend less time on mundane deployment work and increase quality by automating as much as you can.
Coding convention practices
In addition to change management and automation, you should standardize development practices to increase the readability and understandability of the chat bot code through coding conventions. The specific conventions you use are less important than that you use the conventions consistently. Code that follows conventions reduces the cognitive load on the code reader leading to faster development and debugging time.
Dialog node titles
Dialog node titles should be used to indicate clear intent. This is your best place to create short comments in your chatbot so be descriptive!
Many teams store their original dialog script in an external source like an Excel file. If this source includes identifiers for dialog text (ex: IC100) then include that identifier in the title of the dialog node.
Watson Assistant’s development interface includes a search function that searches over dialog node titles, text, and context variable responses. Use node titles to make searching easier — you’ll be glad when you are debugging.
Context variable names
Watson Assistant includes context variables that can be used to track state in the conversation. These variables can be set by Watson Assistant dialog responses or through integrations (for example, from an orchestration layer). Use a naming convention that describes at a glance what the variable is for and how it is used. Go beyond snake_case vs camelCase.
For instance, you may decide that variables set by Watson Assistant start with uppercase characters and variables set by an orchestration layer start with lowercase characters.
Group related variables
Context variables can be simple key-value pairs or can include JSON objects. Variables should be separated by function and should be set and cleared in predictable places.
Imagine a bot that tracks information specific to the current user and current intent and this information must be reset when the bot switches user or intent. The bot could use $user_name and $intent_info as variable names and as long as the bot developer knew all the variables used these could be maintained. But what if new variables are added later?
The bot could alternately use $user.name and $intent.info, where $user and $intent are objects. In this case, the “Switch user” node would reset $user and the “Switch intent” node would reset $intent, capturing all current and future variables stored in those variable groups. Even better, this later approach is more easily understood and predicted. This becomes increasingly important as the chatbot grows more complex with additional context variables.
Conclusion
A chatbot needs to be treated as a first-class code artifact and it must be managed as such. Software development has provided many useful practices that are easily adapted for chatbot development and these practices improve quality and reduce time-to-delivery. The practices in this article can each work independently but compound their power when they are combined.
Get started with these practices now to improve your chatbots! For help in implementing these practices, reach out to IBM Data and AI Expert Labs and Learning.
