README-driven planning for a Digital Garden CLI in Rust
By writing the README first we can explore different
approaches to the user experience of our CLI. We
could think through the entire CLI right now, but we'll
leave other subcommands for later. Instead, we'll focus
on the fact that we know we will have multiple subcommands
and design the command on which all others rely: write.
We can come up with a first example subcommand. Note that
by doing this we are also defining the name of the binary
as garden.
garden write
When writing, users will not necessarily know the title of
what they're writing in advance, so we will not require
them to provide it. This leads us to an optional title
argument. We could have chosen to make this a positional
argument, but we made it a flag instead to delineate from
other potential future positional arguments (such as
--message, which we have chosen not to implement now).
garden write -t "Writing about Rust"
Instructor: [0:00] by writing the readme first, we can explore different approaches the user experience of our CLI. We could think through the entire CLI right now.
[0:10] We'll leave other subcommands for later. Instead, focus on the fact that we know that we will have multiple subcommands in this course and design the command on which all the other ones rely.
[0:20] By focusing on the README, we'll focus on the experience of the users who want to use our tool. In this case, the first thing that we'll hit is the title Digital Garden, which is the name of our tool, and description, a CLI tool for the creation and maintenance of Digital Garden.
[0:43] Now I've already written this course, so I know that we're going to have multiple subcommands. When we think about how somebody is going to write in their Digital Garden, we can think about the things that they are going to want to do. They want to write something. They want to search their documents for specific tags or maybe want to publish a site from those documents.
[1:02] We can immediately see there are multiple separate actions where you're going to want to take on a digital garden. The most basic action we'll want to take is to just write something. In this case, our CLI name is going to be Garden because it's fairly easy to type. It's six letters. It's a lot shorter than typing out digital-garden.
[1:21] The subcommand we're going to use to write is called Write. We've already defined the name of the binary that we're going to use by writing the readme. Thinking about what else we might want to do with this write command, we might already know what we're going to write about.
[1:35] I might want to write about, say, iterators in Rust, in which case, I'll want to give the command a title when I say that I'm going to write. In other cases, I may be taking notes, or I may not know what I'm going to write yet or what I should title it.
[1:49] We'll make sure that the right subcommand can accept the -t or --title flag with the title that we'll use to create the file name with the content that the user ends up writing.
[2:01] I'll add a description here and fix the heading level so that Write is under Commands. Write will open a new file to write in our Digital Garden. Since we don't necessarily know what we want to title what we're writing, we'll leave the title as optional and ask the user for it later if they don't provide it upfront.
[2:18] This README describes our first subcommand. We'll have a binary name, Garden, with a subcommand called Write that takes an optional argument called Title.