Adam Keys is Thinking

The gestalt of what's new in software and how it's changing our world has evolved over the decades.

In the ‘90s, it was “don’t make me think!”. User interfaces went from text-based systems that required memorization and expertise to graphical systems that afforded more casual use of computers. Unix users and their terminals are a notable holdout to this day.

In the ‘00s, it was “don’t make me remember!”. The internet let us to stop worrying about access to common knowledge. Search engines, news feeds, e-commerce, and listing sites made it pretty easy to answer many questions without a resident expert. Nascent social platforms made it possible for our “friends” to feed this information back to us. Notable holdouts: it was impossible for me to search for punchlines from SNL skits, and largely still is.

In the ‘10s, it was “don’t make me describe the content I want to see!”. The now-giant tech companies figured out that their products were more “engaging” if they pushed content to people instead of people clicking around and typing queries to describe what they want. Thus was born machine learning, recommendation systems, and infinite/algorithmic feed scrolling. Notable holdout: none, the blast radius of ad-tech is wide and far-reaching.

From this particular moment, it seems like the ‘20s are going to be “don’t make me leave my enclave”. Even if there’s a breakthrough in medicine and this pandemic is a temporary blip, the writing seems like it’s on the wall. Many kinds of service and retail commerce we used to go out into the world to interact with, along with offices, are going to fade away as climate changes and viruses come and go. Notable holdout: the not-so-middle class folks who do the machine's bidding and keep the wheels of commerce rolling.

Over three decades, things are at once noticeably better and yet there's vast room for improvement. If you're wondering where impactful work can be done in technology, it's in making the benefits of the technology we're building for the middle/upper classes today available to the less fortunate tomorrow. If we can make fantastic televisions available to everyone, surely we can improve the outcomes that matter most in everyone's lives.

If we could bend this curve, the '20s could be the decade of "no pithy quote, just people helping their neighbors."

The Revenge of the Intuitive - Brian Eno lamented the downsides of a modern, computer-based recording console. Twenty years ago! The trade-offs for “freedom” at the expense of human affordances were too much for Eno at the time.

Feels like we’re in a similar spot with developer tooling. It works for the most accomplished and persistent of us. For many people who would like to build software, it’s too much. It’s too easy for our castles of complexity to thwart the novices.

The trouble begins with a design philosophy that equates “more options” with “greater freedom.” Designers struggle endlessly with a problem that is almost nonexistent for users: “How do we pack the maximum number of options into the minimum space and price?” In my experience, the instruments and tools that endure (because they are loved by their users) have limited options

You could just as easily write this today about software development libraries and tools. Too many of them discard pretty good ideas about how to build applications. Too much fascination with meta-tooling. Not enough thought put into how to put applications in people’s hands.

With tools, we crave intimacy. This appetite for emotional resonance explains why users - when given a choice - prefer deep rapport over endless options. You can’t have a relationship with a device whose limits are unknown to you, because without limits it keeps becoming something else.

We need standalone tools and libraries to build upon. However, well-curated, opinionated developers tools are where the magic happens. Frameworks like Rails, Tailwind, Next.js are where the leverage is.

A determined expert can build an application from building blocks. Novices can at least get started with a well-crafted framework. A good community and forgiving documentation can get them through the valleys of confusion to the peaks of accomplishment.

Perhaps low/no-code tools will bring the benefit of the “golden, narrow path” to more people. Maybe the trade-winds of developer tooling will blow away from showmanship back to accessibility. Either way, we should tidy up our house and make software development more welcoming to those who aren’t already monks in the monastery.

I rented a 12-year old Porsche Boxster via Turo this weekend. Good app, great car. I’m shopping older German convertibles for my next car. Paying a little to rent a prospective car for a day is way better than driving one for less than an hour. Plus, no sales tactics!

The center of the Boxster experience, it turns out, is the tachometer and the engine. The tachometer is dead-center, set in distinctly-Porsche numerals with a digital speedometer in the bottom. You don’t want any other gauges. It’s nice to know when you’re about to run out of fuel, I suppose.

The flat-six cylinder engine sits right behind your shoulders. It is, according to my wife, loud. I found it sonorous. I don’t have a picture of it because you literally can’t see it without taking the car apart. And, a picture of a dirty machine with 130,000 miles isn’t right. The engine on a Porsche is meant, and designed, to be heard.

Once I was between that tachometer and engine, I knew I was definitely in a Porsche Bubble. The switches, seats, even entertainment system didn’t matter much. It helped that it was a lovely day and the air conditioner was up to the challenge. But it’s all auxiliary to the sights and sounds.

Turns out, that’s sort of all you need. A strong design center and two senses stimulated can make a product that stands the test of a decade or three.

Features in software are answers to questions. How can customers send what they're looking at to someone else? That's share via email. How can customers distill all the data about my project's tasks down to raw data to analyze it? That's a report, probably with a CSV export.

All of these answers exist on some kind of spectrum. There are simplistic and sophisticated answers. Maybe reporting has no interaction affordances at all; it's an HTML table and a link to download it as a CSV. Perhaps reporting is full of interactions, using metaphors of spreadsheets like sorting or filtering.

It hurts to waste time and effort. We get attached to the things we work on. But that’s the Sunk Cost Fallacy talking. If you don’t think a feature is worth the time it takes to make it great, then it is not rational to ship a crappier version simply because you have sunk time into it.

Julie Zhou, How to Make Things High-Quality

Early in the development of a feature is the time to seriously consider whether to ship the simplistic or sophisticated version of the feature. Before Sunk Cost starts to weigh on our souls. The first few days of building the feature are often about figuring out how much sophistication we can afford to build given the amount of time we have to ship the feature.

It is tempting to stop when it works, but it is only the beginning. That’s the shitty first draft you’d never turn in. Now you must go through the process to make it as simple as possible for others to understand.

Simon Hørup Eskildsen, Shitty First Software Drafts

In a sense, we’re matching a time budget to a mental complexity budget. In one week, we could figure out how to do a very simplistic CSV export. We could get it to work, make the implementation clear, test it out, iterate on code review, and have it ready to ship. In four weeks, we could add all the features that make a crisp and clear customer feature: generating it in the background, emailing a link to download the CSV after its generated, showing progress of the export to a user, etc.

With the teams I work with, we operate with the idea of peak complexity: the time at which a project reaches its highest complexity. Peak complexity has proved a useful mental model to us for reasoning about complexity. It helps inform decisions about when to step back and refactor, how many people should be working on the project at a given point in time, and how we should structure the project.

Simon Hørup Eskildsen, Peak Complexity

Somewhere in the middle of the time allotted to the project, a feature might start to feel like its getting out of hand. Inevitably, there's some surprise complexity or scope that no one anticipated. If the code of the feature were a combustion engine, it is sitting on a stand, partially disassembled, and in need of a rebuilt component.

Maybe we decide that the surprise scope isn't worth the toil and scrap part of the feature. We might decide it is essential and scrap some other part of the feature so we can finish this while affording the time and complexity budget.

Eventually you reach a point where there aren’t any more unsolved problems. That’s like standing at the top of the hill. You can see clearly all the way down the other side. Then the downhill phase is just about execution.

Basecamp Hill Charts

We reach that Peak Complexity, decide how to get through it, and start working downhill. We're now reaping the benefits of the thought and effort we put into managing the complexity budget of the feature, given the our time budget. We're crossing t's and dotting i's, finishing detail work, and getting the project ready to ship.

I find that managing software projects as time plus complexity works far better than viewing it as tasks for people to work on until it's "done".

In the sense that trees of people (managers and reports, ala Taylorism) are the old guard. Data (folders and files) are old sauce and nodes + edges are new sauce.

In the sense that part of the confusion of our modern world is that e.g. the Koch brothers have considerable influence on how the Republican party organizes itself. Thus, money is the speech that organizes our current regime and acts on policy. But the Koch brothers aren’t on the org chart for the government or the Republican party.

In the sense that hierarchical databases are such old sauce that I’ve never used one. People new to software development don’t even realize they were at one time a thing that competed against the idea of relational databases.

In the sense that writing is linear or organized by chapters in books. But, the web is a wild mess of hyperlinked graphs. Maybe writers want to organize by graphs too!

(Spoiler: you can represent strictly hierarchical data with graphs too!)

A lot of us are out here, amongst all the strangeness of the world, trying to figure out how to help our teams adjust to collaborating remotely. It’s long been my observation that nothing beats people in a room together communicating via ad-hoc scribbles on a whiteboard.

Seems like a good time to survey the landscape and see if the situation has improved!

On one end of the spectrum are Google Draw and Jamboard. The former seems better for attempting to draw technical diagrams. I think it's actually better for ironically creating WordArt. The latter seems like an honest, lo-fi attempt to re-create whiteboards online and collaboratively. I don’t think these tools cut it. But, they have the advantage of ubiquity: a lot of companies use Google Suite, so these could come in handy, in a pinch.

Another wild card is to use design software your team might have in place. Sketch or Figma are inherently about visual communication. If everyone has a license and some patience, this could work! If anyone can put some boxes, arrows, and text together, you can basically whiteboard.

I’ve used Whimiscal to create non-trivial visual communications. It works great, it’s easy to share with people, there is some multi-person editing. It's easy to get started in Whimsical and it has some depth, but not so much depth that it's intimidating or overwhelming. Pricing aside, this is where I’d start with my current team.

I have not kicked the tires on Miro, but the concept is intriguing. Looks like there’s real-time, collaborative visual communication/editing. They also brag a lot about their integrations with adjacent project/collaboration tools such that one can embed JIRA cards, mockups, docs, etc. in a whiteboard. If you’re already using this, I’d love to hear your experience with it!

Finally, you don’t need software to share ad-hoc scribbles. You can draw on paper, capture it with a camera, and share that image almost anywhere. You could use sketching/drawing tools to do a fancier version of that. If you have a whiteboard at home, you can draw on it, take a photo, and share it.

It doesn’t matter if the tools aren’t that great or if your company hasn’t adopted any of them. Taking the initiative to collaborate, or having the insight that communicating with words is not cutting it, is much more important.

Remember secretaries and drinking at work? And land-line telephones? And smoking inside? Blech! And an even more unequal society with even more thumbs on the scales?

My wife and I, when we first watched Mad Men:

Oy, Makefiles! And weird preprocessor tricks! And file-scoped variables/memory ownership? And everything is an int, sometimes pretending to be a char.

Me, reading C code, having last written valid, in-anger C code during college

The 1960s and 70s had some nice qualities, but some of them don't hold up to the nostalgia.

Rules won’t solve your problems, but thinking about them might. To paraphrase a couple well-known quotes:

“Rules are useless, but thinking about rules is indispensable”

Dwight Eisenhower

“No rules survive first contact with a toddler”

Helmuth von Moltke the Elder

😉

It’s folly to think we can generate the exact outcomes we want with rules. Every ruleset leaves more unstated assumptions than it generates clarity. The legalese found in contracts, and its absolute obtuseness, is testament to how hard it is to write clear rules.

That said, thinking about how rules, or a lack thereof, generate outcomes is an essential and worthwhile exercise. I like putting things through the lens of macroeconomic thinking to seek out second order effects, unintended consequences, and perverse incentives that emerge from a proposed rule set. Rules are trade-offs!

In short: humans + rules are a strange, not entirely mathematical thing. Think about how bad actors will abuse rules in their favor and how good actors will be constrained by rules in search of the outcomes you actually want. Then, if you must, write as few rules as possible.

This year, I’m trying to better keep in touch with friends, family, and former co-workers. It came to my attention that this is, in many ways, a thing for which you would use a customer-relationship management application. This could work, but seems like a lot to me.

Most software starts life as a) a document/spreadsheet or b) a system of long email threads. In that spirit, I thought I might work backwards from what I normally do: build the littlest CRM I can without writing code or using development tools.

I’ve already got Things and Bear in my workflow. Turns out that duo solves the essential part of the problem. Things reminds me to contact a friend/family/co-worker periodically. I keep notes on what folks are up to, what we talked about, when the last time we talked, etc. as unstructured notes in Bear.

That’s it! I’m only one month into this experiment, but I’ve contacted, at least once, most folks I wanted to. 📈

(…continuing a Twitter thread)

io-ts caught my attention a while back and I finally had the chance to read through it. I’m glad folks are experimenting in this area, particularly with the potential reach into multiple communities and ecosystems that TypeScript affords.

We use dry-rb extensively at work and I was curious how a TypeScript expression of the same idea (define type-like structures at your runtime boundaries) looks.

The flippant response to runtime type systems for dynamic languages is: if you love types so much, why aren’t you using Haskell, Scala, Swift, etc.? That is, a type system over JavaScript or Ruby is a relatively new/unconventional choice.

Gradual type checkers: it works for Facebook and Stripe. Maybe it scales down for much smaller teams and codebases? Weird flex, but okay.

In reality, a runtime type system is easy to adopt and, when paired with some kind of Either/Result abstraction, can be built incrementally by composing types, data coercions to types, and validations of coerced data.

Having spent a year and change working with dry-rb’s runtime types/validations, I’m looking forward to introducing Sorbet. I like the idea of writing types and function signatures for development-time enforcement, but having the option to use some of them at runtime for boundary enforcement.

dry-rb has served us well, but the development experience that I crafted is highly coupled to using a Result/monad-ish idiom. Lots of combinator-envy. Most developers don’t crave this sort of thing.

Even if it’s successfully sold, it’s an uphill battle of education and FP/OO adaptation the whole way. If I were doing it over I’d look to Go’s tedious but easy to teach idiom of checking for errors after nearly every non-trivial operation.

I think dry-rb and io-ts will succeed or fail in very similar ways. Teams that know an ML-like language but are for some reason using JS or Ruby will take quickly to it. Otherwise, there’s an impedance mismatch to manage as they teams their own idioms on top of runtime types.

I’d pitch this to front-end developers as similar to React’s PropTypes, but better.

PropTypes give you greater confidence that you’re passing the right properties to a component and that a refactoring didn’t break things. Type-asserting data structures, like io-ts, give you confidence that the boundaries of your system, e.g. the XHR request/responses and persisting data to local storage, are either well-formed or immediately kick over to failure handling.

Enforcing object shapes (keys and nesting), type correctness (the value for key X is type Y), and validity (values declared as an “age” are always positive integers) at the boundary of your application and between components means you can more code on the “happy path” in your application logic. Conditionals and error handling are largely, but not entirely, pushed outwards to prop types or the boundary type system. This is, in my opinion, living the dream!

The gift and the curse of io-ts and dry-rb’s design is the use of combinators as the center of their design.

The skill ceiling for composing functions to handle network/database requests, type/shape assertions, coercions, and validations is very high. There’s lots to learn about combinators and the more you know, the more you can do. The downside is that the skill floor is also high. The less you know about combinators, the more mysterious, intimidating, and math-y they are.

It’s an unfortunate reality that developers rarely rave about how great a library or language’s error model is. Mostly people put up with exception handling and try to live in a blissful world of error-avoidance and happy paths.

Result types - e.g. Rust’s Result, io-ts’ Either, Haskell’s monads, dry-rb’s Result and monads, Elm’s Result and Maybe - are promising. Function return types that are explicit about whether the thing succeeded or failed (without stack manipulation hijinks) is something we really should have put in practice some time ago. io-ts and dry-rb are existence proofs, to me, that you don’t need an extremely sophisticated type system to make these work in practical, runtime-typed languages like Python, Ruby, or JavaScript. But they can quickly send you down the road of combinators. I’ve found this is not a road developers are enthusiastic about traveling.

Go and Erlang take a different, utterly unsophisticated, road and I wonder if it’s more promising. Functions that can fail (any kind of IO, some kinds of math, etc.) return a success value and error value as an array or tuple. Developers are expected to always check for an error before proceeding; linters and peers will complain if you don’t.

If a linter does it, so can a compiler or gradual type system can too. Maybe the middle ground between the status quo of exceptions and the promised land of result types is compiler-enforced checking of success/error pairs. The advantage is, no invention or re-learning is needed. It’s an array and a conditional. Granted, I’d prefer to get rid of the conditional. But, I’ll take the ease of training developers on the approach as a trade-off.

In short: my new hypothesis is “run-time enforcement of types/values/rules around the boundaries of your system, gradual/static types inside your system to prevent programmer errors”. If you can go further and use a static type system like Rust or Elm to reach the point your software is “correct by design”, that seems like living the mega-dream. 🌈

Prince’s unfinished memoir, The Beautiful Ones is a quick, but awkward, read. The preface is the most coherent, the story of how the editor, Dan Piepenbring, ended up being chosen by Prince to realize his autobiography. It shines an interesting light onto what it was like to be in Prince’s orbit, if only briefly.

Of course, Prince passed away shortly after the book was announced. He had started providing material to his writer in the form of notes and guidance, but only a few chapters worth covering his youth and early career. These notes, in their idiomatic manner of writing, e.g. “👁️ love u”, form the bulk of the book. The rest of the material are photographs and other notes collected with the help of Prince’s estate. They’re insightful, but not particularly coherent.

I’m relatively new to the deep Prince mythology. I suspect I got more out of the book than those already steeped in purple mystery would. There are probably better starting points for those who want to know everything about Prince or who are enitrely new to the Prince mythos.

I just finished reading the Watchmen graphic novel and it is amazing. I was drawn in by the HBO series last year, which amplified my enjoyment of the original story. It might end up in my top five works of fiction.

The story is of its time: the Cold War, superheroes as saviors. Even better, it has timeless themes that feel relevant in our weird contemporary situation: growing authoritarianism and nihilism towards overcoming the status quo to tackle other looming problems.

I saw the Watchmen movie first, several years ago. The movie, as I remember it, holds to the first few issues surprisingly well. The ending of the comic is far superior to the one used in the movie. The comic has more space to expand minor storylines and even introduce a whole other comic within the graphic novel. The comic stands head and shoulders above the movie.

I still feel like the Watchmen HBO series was one of, if not singularly, the best shows on television/streaming last year. The graphic novel is the perfect chaser. Lots of plot points make more sense through the lens of the graphic novel: the whole squid attack, Looking Glass being slightly off, Robert Redford as president.

If it turns out they don’t produce more seasons in the HBO series timeline, at least there will always be the comic. (And Westworld, for the time being).

Highly recommend: get a BB-8 or similarly lovely icon from your favorite mythology on the credit/debit card you most frequently use. I have a couple lovely bonus conversations with folks per week because of it. Sometimes it's "like your card" but sometimes it's full "did you see the latest thing?" and it's nice to talk to people outside my normal routines.

Of note, I get as many comments about BB-8 on my card in a week as I did for Darth Vader in a month. QED the fandom is wrong, bring more fun stuff and less super-serious Skywalker stuff. And don't be cowards, let Chewbacca and Maz resolve their romantic tension!

ps. tip everyone you can until our country’s terrible treatment of people in service jobs improves. They work hard, get paid too little, have basically zero safety net, and serve on the front lines of the "may I speak with the manager" wars.

A nice guide on code reviews (unfortunately no author is attributed on the Notion doc) is making the rounds. If you do code reviews, you should read it. If you don’t, you should start, and then read it.

I do have a personal quibble with this particular guide. I find code review most valuable for “education and context sharing”. I rarely detect bugs or “safety” issues when reading PRs. I’m trying to build this skill, so maybe check back with me later on that.

On the flip side, I want to boost a couple ideas that I wish had been in force for code reviews I’ve given/received in the past:

• “No stylistic preferences” enforced by humans. This is indeed what linters and style guides are for. If you object to the use of linters, I can’t help you.
• “No blocking tips”. Lately I’ve tried leaving comments that start with “not a blocker…” followed by an idea on how to make code clearer. This gives the code author the option to address it immediately if they have the gumption, return to it later if they don’t, or take it under consideration for the future.
• “Any PR that introduces…a security or privacy issue should be blocked”, in particular user privacy/safety issues. I’m lucky to work on a team that is considering user safety and data privacy very early in the process, so we often don’t come across these issues as late as code review. That said, expanding code review scrutiny to include ways that customer data could be leaked or people could act maliciously feels like a cultural win.

Lastly, this whole paragraph hits home. Onboarding and “mind-melding” is possibly the second most important thing to keep in mind regarding code review in the year 2020:

Nobody went to school for hacking on your company’s stack. Outside of software fundamentals all of us had to learn how to make things work while on the job. Code reviews are one of the best ways for us to share knowledge and context about different ways things are done or tricks we’ve figured out to get things done in better ways.

In my opinion, the most important thing to remember about code review is that it is often the worst time to offer non-trivial feedback. Most pull/change requests land when a project is wrapping up and the author is ready to ship the thing. This is the riskiest and most frustrating time to make substantial changes. If you want to improve code design and practice, pair programming is the better tool, not code review.

As a manager, I hear about things that are interesting and things that probably need changing.

“We want to do three projects but only have two teams.”
“The next production release is held up by this one task that needs seven people to agree on a minor but complicated detail.”
“The backend team has to spend the next week upgrading dependencies to meet new security requirements from the operations team.”

Lots of work to do there. Eyes bigger than stomachs, weird coordination issues, past decisions piling up and haunting us all at once. Assembling these data points into a theory of how the organization works, without falling victim to us-vs-them narratives and cynicism, is an essential challenge of management.

On the other hand, I hear things that are categorically good.

“Alice has saved us a ton of work this week.”
“Bob did fantastic work on this product and we’re going to ship early.”
“Carol stepped up and coordinated everyone when the project lead had to take a few sick days.”

In my few years of leading and managing teams, these are the best kinds of things to hear. Something about people is working here. They’re turning accountability for their work into positive outcomes.

Stacking repeated positive outcomes yields trust in people and teams. That yields agency to tackle future projects in creative, potentially better ways. That usually leads to even more positive outcomes. Even more importantly, it makes for teammates who are excited and satisfied by their work.

Bringing teams together across an organization to make positive outcomes for people who are excited about their work: that’s when management feels like it is clicking.

As unreleased material trickles out of the Prince estate, some fantastic stories have emerged. I haven’t yet read The Beautiful Ones, but even the stories that aren’t part of his incomplete autobiography are top-notch Prince mythology.

Prince hired a DJ to play music for just him and his date:

“And then it hits me,” WallyWaves writes. “There’s only two people in there. Prince and a girl. I’m not there to DJ a private party. I’m there to DJ a date. Prince is on a date and I’m the entertainment.”

Prince shopping before Tower Records opened:

Mike: "How do you want to pay for this? Would you like us to ring it up now?"

Prince: (smiles)

Jerome: "Yeah, talk to THIS dude, here's his number, he'll handle it." (hands us digits for the President of Warner Bros. Records)

Finally, for all your conversational and expressive needs, an Official Prince GIF Archive.