Why did we do this study?
Our command-line interface (CLI) is OK but not great. It will be useful to generate a set of design principles to base the CLI around — but not change what’s working well (which is a lot of it). So let’s do it!
The CLI is the main entry point and interface people have (currently) for Gatsby. Everyone sees it! So it has a huge influence on people’s experience of Gatsby.
We’re going to create a CLI style guide and then implement that style guide, which includes redesigning error messages, introducing gatsby --quiet as a default mode and make more extensive use of the gatsby --verbose flag. To make the CLI easier to design and improve, we’ll implement Ink. To optimize the CLI design, we’ll use the data being collected through our telemetry setup, which collects data about CLI usage (opt out is possible).
What did we learn?
We conducted 4 usability tests with awesome Gatsby users to learn how they do tasks using the Gatsby CLI and how they use error messages to debug their projects. Thanks Simon Koelewijn, Gene Smith, Jonathan Prozzi, and Benjamin Lannon for teaching us how you use the CLI, and thanks to @sidharthachatterjee, @wardpeet, @pieh, @m-allanson, @gillkyle for copiloting the interviews with me and helping turn what we learned into action.
If you want to be part of future usability tests, sign up here.
We also did a thorough search of other CLIs and style guides to learn what we’re doing well and where we might be falling short. Here are resources that informed our knowledge of problems that Gatsby CLI has and possible ways to solve those problems:
- Evaluation of other CLI tools
- Nielsen Norman Group 10 usability heuristics
- Nielsen Norman Group error message design
- Heroku CLI style guide
- 12 Factor CLI Apps
- User journey through the Gatsby CLI (informed by usability interviews and the Gatsby core team’s observations of what issues are most common regarding the CLI)
What do we need to do?
- Crunch some numbers to find out “what are the most common error messages people get?”
- Make error messages better, starting with the most common ones
- Create a CLI style guide and make sure the CLI starts matching the style guide
- Do some other things that will make the CLI easier to use (easier = takes less time to do a task and/or is less frustrating). See issues tagged with
topic: cliin the OSS repo!
Want to dive in and help / comment?
Get consensus on the Error Survey RFC & CLI Redesign RFCs start on the changes they suggest!
All the related issues will be tagged with topic: cli in the OSS repo.
List of issues (some already have PRs in progress):