Adventures in prototyping a Command Line Interface

As a “designer who codes,” I actively seek ways in which coding can facilitate my work. And until recently, I was of the mind that prototyping in code was an activity reserved wholly for the world of graphical user interface (UI) design.

Boy, was I wrong. After receiving feedback on my side project that helps designers and developers build living styleguides (Runway), I quickly learned that the techniques of rapid prototyping and usability testing can just as easily be applied to any workflow or interface, such as the command line interfaces (CLI) that developers commonly use in their work.

The ‘help’ output of Git’s CLI

This was an exciting revelation. In my experience as a designer I have enjoyed countless opportunities to prototype UIs and conduct usability tests around specific workflows and features. Never before, though, had I embarked on a journey to prototype and test a CLI workflow. Not knowing where to start, I rolled up my sleeves and turned to a familiar friend for prototyping in code, Javascript.

In this post, I will walk you through (at a high level) my process for prototyping and testing one of the main workflows in the application: creating a styleguide, given a source file and a few configuration parameters.

If a picture is worth a thousand words, then a prototype is worth 10,000. Prototypes go beyond the power of show and tell — they let you experience the design (Prototyping, A Practitioner’s Guide: Todd Zaki Warfel)

Context

Feedback is the lifeblood of improvement, and the Runway team has gotten loads of it since our launch last year. Indeed, one of the most frequently asked questions has been:

“When will Runway support creation of styleguides via a CLI tool or API?”

From the outset we expected this feedback. Working under the assumption that designers would be our primary users — and that they would shy away from an entirely CLI-based experience (for example, Hologram) — we deliberately focused our first iteration around a comprehensive UI experience.

And yet the most resounding feedback came from developers, who were looking for a lightweight way to build living styleguides — particularly one that could be automated or easily integrated into an existing CI/CD set up. Moreover, both sets of users were frustrated by how many steps it took to act upon Runway’s value proposition: “Go from stylesheet to styleguide instantly.”

Enter my (admittedly) self-indulgent scheme: prototype a CLI-experience that can be leveraged by both designers and developers, and conduct user testing to assess its feasibility and usability.

The Plan

Since it was both risky and costly (in terms of development effort) to build a functional CLI tool without user feedback, I sought out to do what I as a designer do best: build a cheap, fake “prototype” that can be used to solicit feedback and de-risk future development work. And if we are being totally honest, I know I did not have the technical chops to build a functional CLI in an efficient manner. Faced with such a quandary, I employed a tried-and-true design tactic: fake it ’til you make it.

As a Javascript junkie, I surveyed the landscape for recommended CLI tooling and quickly landed upon the Node-based Commander.js. Using a Node-based tool meant that I had the world of NPM at my disposal, enabling me to use libraries such as Colors.js (for fancy, colorful terminal output) and Node Spinner (for showing a spinner during simulated, asynchronous actions).

Getting Started

Like most Node projects, I started by generating a package.json file and saving the three aforementioned dependencies to it. Per the README for Commander, I created a file called runway.js and prepared to prototype.

For context, Runway users can currently create styleguides through a UI by uploading a CSS/SCSS file with specially formatted comments. They can give their styleguide a name, and have the ability to specify: A) a layout; and B) a syntax highlighting theme.

I wanted to prototype the CLI experience in an iterative manner, knowing how long it took us to land on the aforementioned UX. And so, I envisioned starting with a new-styleguide command that would take a single argument — a stylesheet — and would return a URL to the user.

The mechanics of Commander are fairly straightforward. You define a command, provide an optional description and set of options, and map it to an action (which is a Javascript function).

One of the coolest features of Commander is that it automatically builds a help page that lists all of your commands and their respective syntaxes. So, by punching ./runway.js --help into my terminal, I got the following output.

HALP

Score! With things wired up, I began tackling the UX around creating a new styleguide. For the happy path, a user should be able to provide a source stylesheet and be given the URL of their styleguide in return, formatted thusly http://runway-app.cfapps.io/styleguide/:id. Using some Javascript magic, I generated a random number for the :id parameter of the URL.

Happy path!

Spicing Things Up

In the real world, it would likely take a few seconds for the styleguide to be created. To reassure users that Runway is handling their request, what if we showed some kind of spinner with an informative message? I leveraged the aforementioned libraries, Colors.js and Node-Spinner to achieve this effect.

Async, methinks.

Getting Fancy

Through the Runway UI, users can specify the name of their styleguide and choose a syntax highlighting theme. Commander makes it easy for users to pass these values through as options, and provides a mechanism for setting default values if they omit one. Commander also allows us to tailor help messages on a command basis, which means that we can communicate to our end-users the complexities of (or liberties we’ve taken on) a particular action.

In this case, I wanted to allow users to choose between three syntax highlighting themes, monokai, solarized, and github, defaulting to the first if none was specified. But since this CLI experience lacks the affordances found in the web UI, I felt it imperative to communicate that decision in the help menu of the new-styleguide command. Thankfully, Commander exposes a straightforward way to do so.

Selecting a syntax highlighting theme through the UI

HALP, redux

Final Product

User Testing

I am still in the process of conducting user testing around this experience, framing usability sessions around the following Task Scenario:

The designer on your team just added several Runway comments to your app’s main stylesheet (main.css) and you need to generate a new styleguide for him. You’ve just installed the _runway_ CLI globally.

Unsurprisingly, and given the scope of the task, developers have largely been able to generate a styleguide with ease. My biggest takeaway was how heavily developers relied on the help menu to familiarize themselves with this new CLI tool. This makes sense, considering affordances are lacking for CLI and command based tools. But it was enlightening to see a handful of developers follow the exact same steps to get up to speed and ultimately complete the task.

This has been a phenomenal learning experience, one that has illustrated how easy it is to apply the techniques of iterative design, rapid prototyping and user testing to a medium that isn’t a user interface.

I covered a lot of ground in this post, and admittedly hand-waved lots of the detail. If you’re interested in any particular facet of this workflow (be it coding or process related), please let me know. I’m more than happy to chat.

If I have done my job here, I have communicated how painless it is to prototype CLI experiences with code. This is not to say that code is the best (or only) tool for such an endeavor. As we designers know, prototyping tools and techniques abound. At the end of the day, one’s choice of tool ought to be a function of:

• The fidelity of design or interaction that one needs in order to test a hypothesis
• One’s facility with the prototyping medium — be that code, paper, visual design, etc.

And although I didn’t explore alternative means of prototyping in this scenario, I’m confident that we can apply the technique and rigor of iterative design to CLIs, just as we do for our UI-based experiences.

Links

mattrothenberg/runway-cli_Contribute to runway-cli development by creating an account on GitHub._github.com