PANTHEON  |  Terminus Discoverability and Official Manual

To support some of our developers' preferred way of working, we support a Command Line Interface (CLI) called Terminus as an alternative way for users to interact with Pantheon tools and their sites. Since we know that developers who use Terminus can become more engaged on the platform, I led the research and design for an initiative to increase usage and improve the CLI user experience in order to increase the number of active developers.

USER RESEARCH

Which problems should we focus on improving?

We began with user research to learn more about the value Terminus brings developers who use it already, what top tasks they use it for and why. We also needed to learn why Pantheon developers might choose to not adopt Terminus, so that we can define an approach to proactively communicate the value to them and reduce barriers to adoption.

RESEARCH OBJECTIVE

What value does Terminus bring existing users? 

Benefits

We learned developers' top reasons for using Terminus.

Save time and reduce error

Terminus brings speed and automation to workflows, enabling developers to more quickly accomplish tasks. For example: in the Pantheon dashboard developers must apply CMS core updates to sites one-by-one. With Terminus, updates can be applied in bulk or developers can create their own script to automate the task. Task automation also reduces the potential of human error.

Convenient when working in multiple applications

Developers use Pantheon within a larger ecosystem, and if a developer is already working on the command line in other applications, it is more convenient to stay in the command line. The seconds lost context-switching from navigating between applications and keyboard to mouse modes add up over time.

Only way to debug certain issues

When debugging, sometimes the Terminus output is the only way to find the problem (such as, if the WordPress white screen of death occurs).

RESEARCH OBJECTIVE

Why do Pantheon developers choose not to use Terminus?

Barriers to entry

Developers who have never tried Terminus described these barriers they felt.

"What is it?"

This was the most frequently reported response. If a developer doesn't already know what it is, it is impossible to even know a CLI is available as an option.

"Why should I invest time in learning a new tool?"

It is a big ask for developers to spend time trying out yet another tool to learn if it will help their workflow, especially when the value isn't clearly and proactively communicated.  The existing scattered and often out-of-date documentation made it challenging to find answers, plus there was a lot of tribal knowledge hidden in power user groups.

"What value would it bring me over tools already ingrained in my workflow?"

We found the majority of Pantheon developers regularly use drush (Drupal's CLI) and/or wp-cli (WordPress's CLI). Therefore, comfort with the CLI is not the problem; the problem is that it is unclear to developers why they need to add yet another tool to their toolbox.

We concluded the primary problem worth addressing is discoverability and lack of useful information in one place. Additionally, while documentation provided installation instructions, that's where it stopped - after a developer installed Terminus they were often at a loss how to proceed.

One user told us: "[Documentation is] often in different places: github, blog posts... there doesn’t seem to be a unified source of information.”

PRODUCT APPROACH
 

Through synthesis and conversations with stakeholders, we formed the following approach

Create a Getting Started experience to enable developers to connect with the value Terminus can bring to their workflows, and get developers up and running easily with Terminus and apply it to their real working environment.

1  /  Communicate what Terminus is and its purpose.
2  /  Streamline the installation and setup process.
3  /  Start developers off on the right foot by providing high-value scenarios already proven by existing users. 

1  /  TERMINUS MANUAL

We created an official manual to consolidate information and become the single source of truth

A first-class citizen

I proposed creating an official manual in order to make Terminus more discoverable and to act as the single source of truth developers can rely on.

I created several wireframe passes to use as discussion tools with the team, quickly iterate on ideas, and to user test to make sure we designed a useful manual for developers to learn Terminus. I worked closely with the technical writer to document real world examples based on what we learned from the user research.

Communicate the value

The "Getting Started" front page provides an overview and context of Terminus is, and how it will support developers workflows. It highlights the top advantages of using it.

Address inherent CLI challenges

I took advantage of having our own team of engineers nearby, and learned additional challenges from them from working on the command line in general. For example, when working on the command line developers have to recall the correct command to use. It's harder to recall what you need (rather than be able to recognize it which is an advantage of a user interface). To make it easier to find specific commands, we added a realtime search to the command reference section.

We also added a "Copy" button to the Manual and in all sections of the documentation so that users don't have to manually select all of the command and worry about missing some of the text. Interestingly, in a comparison test, more users found and used the button with the "Copy" text versus the icon

Show how Terminus can be extended

A powerful ability of Terminus is that it can be extended through plugins from both Pantheon engineers and the community, enabling developers to fill in the gaps for what they might need it to do.

This plugins directory provides a destination for community developers to share their plugins and for new developers to find ways to improve their workflow.

Reusable design

The technical writer/developer and I collaborated on designing and implementing this framework, which became the first of its kind for our documentation. The framework was reused later in other guides the documentation team created without design help.

2  /  EASIER TO INSTALL AND TRY OUT

We designed a streamlined installation experience and put usability principles into practice in the CLI

Setup is easier to understand

We improved the installation experience by identifying the user's OS and auto-selecting the appropriate installer. We also clarified dependencies - previously a source of confusion.

A more intuitive CLI experience

During this, the engineering team worked on releasing a version 1.0 of Terminus itself. I worked with the team to improve the usability so that it is user friendly, consistent, and trustworthy, so that it becomes more likely that developers who try the tool will stick with it.

Help developers find what they're looking for

We improved the help output so that the visual design is more skimmable, and the content more understandable.

Consistent command structure

We defined a consistent structure for all commands to follow. Pre-1.0, the structure was inconsistent which made commands difficult to remember.

Informative output and feedback

Before 1.0,  sometimes there was no output when Terminus was running an operation, which caused uncertainty as to if the operation was successful or whether it was running at all. We improved this so Terminus now outputs more informative success and error messages, and communicates progress when executing a command.

3  /  SCENARIOS

We set developers up for success with real-world, relevant use cases

The Example Usage section became a major investment during development. We guide developers through the high-value scenarios as defined by existing users, such as applying CMS core updates to all sites at once.  This section helps developers apply this immediately to their own work and experience results faster than figuring it out on their own.

Screenshot of the current manual

When the Terminus Manual launched in 2016, it became the top-ranked section of our entire documentation. Two years later, it is still consistently one of the top-ranked sections, and still often takes the top spot.

© Kim Kiser Ramirez 2020