rewrite Dev Journal: How Progress Doesn’t Feel

Sat, 26 Oct 2019 18:30:00 -0400

Assumed Audience: practitioners or interested lookers-on for software development—especially indies.

Today, I had about 3½ hours dedicated to working on rewrite and I did make progress… but it sure didn’t feel like it.

For the past month or so, I’ve been sidelined from working on the project by way of getting very sick and then being swamped with travel for a conference followed by a friend’s wedding. I resolved, however, to get some things done today. I enjoyed that sense of momentum I had in those first couple weeks I was working, and I want it back.

Today’s work, however… felt exceedingly unproductive. It wasn’t. I was learning. Specifically, I was learning how Swift Packages and the Swift Package Manager (SPM) work, how they work with Xcode, and what they can and cannot do. In general, learning like this is necessary and valuable, and this specific knowledge domain is particularly necessary and valuable for me. For one thing, the details of how I’m building the app will make this very applicable very quickly. (More on that in a future update.) For another, because I work best when I have a good understanding of how the whole system works together.

The net of it, though, was that I came out with a good idea of how to use Swift Packages… and zero new lines of code written for the app itself. I may yet make a little progress this evening after my little girls are in bed, but the big takeaway for me today was the need to remind myself that learning is a form of progress. You might think that I, academically-minded and hyper-nerdy fellow that I am, would find that easy to remember. It turns out, though, that it isn’t easy to remember in the context of the desire to actually ship something!

I hope this dev journal entry serves as an encouragement to others doing development work. There’s value in these days. They’re not failures. They’re an integral part of the way you get to the day when you actually ship.

I know this because I’ve been here before. There was a time when I had no idea how I was going to ship that PHP app and I spent whole afternoons figuring out something about SVN—afternoons that did not feel like part of shipping, but which ultimately led me to recover from accidentally deleting my entire codebase. There was a time when I had no idea how a JavaScript “single page application” (SPA) could actually work, and spent multiple afternoons reading about API-driven applications—afternoons which did not feel productive, but ultimately led to the point where I’m in a technical leadership role on one of the biggest SPAs in the world. So I can say fairly confidently that however unproductive this afternoon’s work loading up an accurate understanding of SPM will yield dividends. And sooner than it feels like today!

rewrite Dev Journal: How I Started

Wed, 04 Sep 2019 21:30:00 -0400

Assumed Audience: practitioners or interested lookers-on for software development—especially indies.

This week, I started the actually writing software phase of working on rewrite. As of yesterday evening, I actually have a bit of code that, although useless in every way, and not especially attractive, does in fact displays a single reference on an iPhone screen. I have an incredibly, impossibly long way to go.

It doesn’t matter: I started.

I had the day off on Monday courtesy of Labor Day, and I chose to spend the chunk of it that wasn’t focused on chores and housework and family time on actually getting this thing moving. I’ve been dreaming for over four years now. That time wasn’t wasted, by a long shot, but as I noted in my announcement post, you can plan forever… or you can just start building at some point.

The problem I had—as I noted back in July—is that I didn’t actually feel like I knew how to start. This a mammoth project, for one thing. For another, doing this kind of indie work requires dramatically improving my design and product chops. And of course, developing for native apps means learning whole new technology stacks as well!

I’ve known all along that the only way to get anywhere was to break the problem down. You know: the same as always in software development. Find something small to start on. I had already identified which part of the app to dig into first: reference management. This is a place where I could have something that is useful to me in reasonably short order (I want to be able to update my own reference library on my iPad!). Even that was daunting, though—still far too large.

So, Monday, I asked: What is the smallest possible reference-related functionality I could build? The answer, I concluded, was: just display an existing library of references. Then I went further, because “display an existing library of references” is surprisingly complicated. It involves, at a minimum:

defining how to display a reference
- …and therefore also designing the data structures representing references
actually building that display
defining how to display a list of references to the user—which things to include, which not to, etc.
actually building that list
making it so that tapping on an item in a list displays the detailed view defined previously
making it so you can get back out of the detail view to the list view again
loading a list of references from somewhere, e.g. a BibTeX file from iCloud Drive
parsing that list of references into the internal data structures designed to represent them

Now, for an experienced iOS or macOS developer, some of those things might feel trivial enough that they don’t even warrant their own bullet point. But I’m not an experienced iOS or macOS developer; I have no idea how to do any of this! What’s more breaking it down that way means that I have small, discrete tasks that I can go after in small blocks of time. Remember: this is a side project, which I am fitting in around my day job, my church commitments, and time with friends and family. I have to be able to make progress in small blocks of time! I have to feel that progress, at least a little, so that I can keep going.

Every bullet point on the list I came up with represents a discrete item of work. It not only may but must be small, so that I can do it in an evening or three. It needs to be done in such a way that later steps can build on it—but it doesn’t actually need to be anything like what those later steps will transform it into. It just needs to be enough to keep momentum moving, and done in such a way that later changes are not too difficult to make.¹

Monday evening, I took the items I had identified and turned them into GitHub Issues in a GitHub project, called Display a BibTeX Library. (I’ll talk about how I’m using GitHub projects a little at some point in the future; it’s a nice flow so far.) Every single one of those items, no matter how apparently small, got its own card. One of them, about Swift-Rust interop, got a note saying, roughly, “I’m pretty sure this will need to be its own whole sub-project.” And looking at that list… I felt a lot less daunted! Every one of the tasks involves something I don’t know how to do yet—but only one thing I don’t know how to do yet, not many.

Last night, I took the first item on the list: display a single reference item. Not parsing them, not even from a string hard-coded into the app, and certainly not loading a file or anything like that. Just hard-coding in a data structure and displaying it on the screen. And, over the course of a few hours, including lots of searching² for answers about specific SwiftUI error messages,³ I managed to implement that one thing.

As I said above: it’s useless in the strict sense. It’s not especially pretty, either. But it’s progress. I started. And now I have that little sense of momentum, and I can keep going!

If you think this sounds like the ideas current in the best parts of agile software development—working to make future changes easy; iterating rapidly; delivering the smallest possible chunks of value, and doing so continuously—you’re not wrong!↩︎
“Searching,” not “Googling,” because I only very rarely Google anything. I search, with Duck Duck Go as my starting point and its ! search commands as power tools for searches in specific places.↩︎
Wow could SwiftUI’s compiler diagnostics use some improvement! I sincerely hope that the Swift team in general and the SwiftUI folks in particular take a close look at Rust and Elm for inspiration here.↩︎

Chris Krycho - rewrite dev journal

rewrite Dev Journal: How Progress Doesn’t Feel

rewrite Dev Journal: How I Started