Usability testing for APIs (and other textual interfaces)

Al Sweigart put together a text-based adventure system in Python. It’s pretty awesome. (read more)

What’s an API?

Honestly, I used the term API because it gets the most hits. I’m really talking about any text-based interface, whether that’s a library for a programming language, a Unix-shell based program, a text-based adventure game, or a chatbot.


Textual interfaces have some unique qualities that make them fundamentally different than graphical interfaces.

Difference 1: You can type *anything* next

In a GUI, the user’s choices are constrained by the on-screen elements. If your dialog box only has six buttons and two fields, there are only eight things the user is going to interact with. And for each one, there’s only a handful of gestures — clicking on buttons, entering text, maybe swiping around a scrolling region.

Difference 2: The interface is part of a larger interface

Every text-based interface is really part of a larger whole, which has its own set of rules and expectations. ZORK-like games, you expect to have an inventory, navigation controls like (s)outh or (u)p, and perhaps to be able to use a handful of well-known verbs (examine, take, etc.) on many things in the world.[2]

Difference 3: The name *is* the interface

This is a consequence of a text-based interface. The name for something is the thing itself; cd is cd, and maybe you know it means “change directory” and what a directory is, but it’s immaterial. Users end up thinking about it as “the cd command”, and that’s fine.

Difference 4: It’s just text

This is the crux of the matter. These interfaces are, largely, “just text”.[3]

They’re Still User Interfaces To Me

A final note for experienced UXers who might be faced with the daunting challenge of supporting a text-based product. After all is said and done, they’re still UIs, interfaces between a computer and a human, and all your regular knowledge and know-how applies. Things have to be discoverable, understandable, differentiable; the gulfs of execution and evaluation should be kept small; and so forth.



Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Alex Feinman

Alex Feinman

Obligate infovore. All posts made with 100% recycled electrons, sustainably crafted by artisanal artisans. He/him/his.