To support some of our developers' preferred way of working, we support a Command Line Interface (Terminus) as an alternative way for users to interact with Pantheon tools and their sites. This project was intended to improve the CLI experience, while increasing usage and adoption of Terminus, which we know can lead to more active users on the platform.
User Research
We intended to learn how existing Terminus users use and gain value out of the tool, and what the roadblocks are to using it. This will enable us to form an approach to help others get this same value by lowering the barriers and making it more accessible.
Our goals for user research were to:
- Define the value Terminus brings Terminus users
- Understand why non-Terminus Pantheon users choose not to use Terminus
Barriers
Users who have never tried Terminus described these barriers they felt:
- "What is it?"
- The most frequently reported response was users don't know what this is. Terminus has only a small official presence on the Pantheon site. Our engineers maintain an open-source GitHub repository for it, but if you don't already know about about the tool it's difficult to find. Knowledge is largely tribal and contained in a power users group (which is also undiscoverable if you don't already know about it), or in the GitHub documentation, which users reported as often scattered and out-of-date.
- "Why should I invest time in learning a new tool?"
- It's a big ask for users to spend time trying out yet another tool, especially when the value isn't clearly communicated, which leads to the third barrier...
- "What value would it bring me over tools already ingrained in my workflow?"
- Some users already use and are comfortable with a command line. For example, they use Drush (Drupal's CLI) or WP-CLI (WordPress's CLI). Comfort with the CLI isn't a problem for the majority of users who would use it - the greater problem is it is unclear why users would need another CLI tool for their Pantheon work.
Benefits
Existing Terminus users described these top benefits they gain when using Terminus:
- Speed and Automation - to work more efficiently.
- Ex: in the Pantheon dashboard GUI, users need to apply core updates to sites one-by-one. With the CLI, they can choose to apply updates sequentially or kick off their own script that automates this task. Both approaches save time and reduce the potential for human error. According to one user, "We run a lot of sites and have few people to run updates."
- Preference and Convenience - some users prefer the command line
- Ex: Users use Pantheon within a larger ecosystem, and if a user is already working with the command line for other work, it's more convenient for them if they don't have to switch applications and context-switch working modes from using the keyboard in a CLI to using a mouse in a GUI.
- Some tasks are only possible through the CLI
- Ex: When a user is debugging site code, sometimes the output from Terminus is the only way to find out what's wrong (such as, if the dreaded WordPress white screen of death occurs).
Our approach
Our main problem is discoverability and lack of useful information in one place. While existing documentation provided installation instructions, that's where it stopped. If a user chose to install Terminus, after installation they were at a loss of how to best configure it for their set up, as well as how they could starting using it right away. One user told us, "[documentation is] often in different places: github, blog posts... doesn’t seem to be a unified source of information.”
After synthesizing the research, we formed this product goal:
Enable non-Terminus users to connect with the value Terminus can bring to their workflows, get users up and running easily with Terminus and apply it immediately to their real work environment.
Specifically, we will create a Getting Started experience by...
- Communicating what Terminus is and what it is used for
- Making it easier to install and configure
- Standardizing commands that are intuitive and inline with CLI best practices, so users can apply prior knowledge and experience.
- Starting users off with a set of scenarios they can use immediately. We'll leverage high value scenarios already proven by existing users.
Terminus Manual
To address points 1, 2, and 4, I proposed a manual to consolidate information and use as an official, Pantheon-backed single source of truth. We also direct people there to learn about Terminus and what they can do with it.
After it was released, the Terminus Manual became consistently the top-ranked page of our entire documentation.
The Getting Started section provides an overview of what Terminus is and how it can be used to support users' workflows. This is an improvement over the previous documentation, which jumped right into installation without providing enough context on what it can be used for.
I worked with the PM, lead engineer, and technical writer to document real world examples for users to take and apply to their situations immediately.
The Example Usage section was our biggest focus in creating this official documentation, in order to provide users with real-world cases that are relevant to their situations.
We improved the installation experience by identifying their OS and auto-selecting the appropriate way to install, and clarifying the pre-requisites. Once users finished installation, we recommend they review the Example Usage section, so that they can learn how to use Terminus in their workflow immediately.
A challenge of any CLI is to recall the correct command to use. We added a responsive search to a full list of commands, on a dedicated page, to make it easier for users to find a specific command they need.
Version 1.0
During this, engineering team was working on releasing a version 1.0 of the tool itself. I worked with them to address point #3: standardize commands that are intuitive and inline with CLI best practices, so users can apply prior knowledge and experience.
From the research we defined principles and best practices to improve the usability of Terminus, so that it is more consistent and trustworthy.
- Improve output - use success messages, give feedback when commands are in progress, use helpful error messages that inform users how to fix the error, and be consistent in the verbiage and tone of all of the above
- Improve visual design - format the text so that it is more skimmable, and use color coding to help communicate status at a glance.
- Terminus style guide - especially as this tool is open source, create a style guide of code guidelines to ensure the consistency we build internally remains so.
Unused ideas
We discussed ideas for deeper integration of Terminus into the dashboard which we didn't end up investing in, such as:
Since setting up automation is a huge reason to adopt Terminus, we discussed enabling the ability to set up scripts through the dashboard, though we weren't able to prove this was a needed feature.
We discussed creating a place in the dashboard for team members to put their shared scripts, to support collaboration and reduce time individuals would spend creating their own scripts. However we determined teams likely already use GitHub (or similar) for sharing code like this.
No comments.