jonoropeza.com

Making software and software development teams. Mostly the people parts.


Ernest Hemingway's Writing Technique (That Works For Writing Code Too)

About writing, Ernest Hemingway had this to say:

The best way is always to stop when you are going good and when you know what will happen next. If you do that every day when you are writing a novel you will never be stuck. That is the most valuable thing I can tell you so try to remember it.

You should always stop when you know what happens next.

This has nothing to do with stopping, by the way. It has everything to do with the difficulty of starting again. The unspoken premise of the quote - the part of the iceberg that's below the water, to just keeping rolling with Papa - is that inertia is powerful, and getting started is the hardest part.

If you know what happens next, then starting again is easy.

And once you're rolling, you've got momentum.

I've written a novel, and I've written software big and small. These are completely different skills but a lot of the frameworks, processes and pitfalls are similar. Just like a novel, a software project develops threads and themes and patterns and a voice. You want to produce in a sprint, a month, a quarter a thing that is logically consistent and emerges at a consistent pace so you and your teammates (editors) can shape it, critique it and hone it.

For me, when I apply this to coding, I try to end each session when I know exactly what work needs to be done next. For example, towards the end of the day on a project to build a new product page, instead of trying to squeeze a few more lines of code out or fixing a bug, you might stop and write the following note to Future You:

Next step: Add inventory to the product route.

  • fetch inventory
  • render it on screen
  • interstitial (spinner) and error handling
  • think about retries and caching, probably not but at least explore it and make notes
  • observability and monitoring, how will we know if it's down, add a test or two
  • come back to that bug in the product description

And it's there for you at the start of the next day.

Contrast this to how many of us work, which is trying our hardest to completely finish something every session. Often ending up either with a mad dash to the finish that burns you out for the next day, or failing and falling short which bums you out for the next day.

Here's what the two ways of working look like visually:

That's your work until it's done pattern in Red, and then Hemingway's system in Green.

The important two things to note are that Red had a cold start at the beginning of a task four out of the five days (compared to one on Monday for Green), and that Red had to push extra hard (maybe getting to work early or staying late) on Friday while Green had a more evenly paced week.

A trick to this system is to make the first task an easy one to get you going with a win. So in the above example, only start by fetching the inventory if the endpoint is known, you already have the creds, you already have patterns in your app for fetching etc. If not, I might start by mocking it and putting it on the screen. Piece of cake.

A potential benefit to this system in software - and I don't have any data to back this up, but I have a strong gut feeling that it's true - is that a significant number of bugs are written and patterns violated when we're stretched and stressed. The traditional way of working produces two stressful states that the Hemingway method avoids: The cold start at the beginning of a session, and the rush or grind to finish a deliverable at the end of a session.

Finally, it should be noted that Hemingway's technique can be applied at multiple levels of regress. Hemingway wrote daily, so the advice came from the perspective of stopping one day and picking it up the next. But you can apply it to your morning session and your afternoon session. Or to pomodoros, or maybe most realistically to those days when you have 8-10 to code, then you have meetings, lunch, more coding 1-2, another meeting, then finish out the day with a third coding session from 3-5. Finish each coding session at a good stopping point, and then spend the rest of the time writing out exactly what comes next.

posted in Software Engineering


Models of Automation

With Bitcoin price weakness and the novelty and/or wonder of the latest ChatGPT iteration pulling our collective heads out of the Web 3 space, I've been thinking about the models of automation, the variables used and how they're chosen.

To illustrate the models, let's use an example of making a service that provides answers to questions such as "what are the approved treatments available for this or that disease" based on the latest biomedical literature.

There are at least five models we might use to enable this service, they are:

  • No automation at the core
  • Automation as Sentry
  • Automation as Helper
  • Autonomation
  • Full automation

No automation at the core - The human does the thing. You're dealing with a small local company, you call a phone number or send an email, a human answers the phone or replies. I used "at the core" deliberately because a modern phone call or email relies on a lot of automation to move information around. Here I'm referring specifically to how the service creates and ships the answer to its queries.

If we don't use automation at the core of our service for looking up treatments, human operators are answering each message without anything automatic happening to either help them, guide them or guard them against bad or wrong answers. This is the default state of any operations-driven company that hasn't set up their service tech-first. There's nothing wrong with it. And nothing particularly exciting, either.

The sentry - The human does the thing, with warnings provided by machinery. Think collision detection in a car. Or a data entry form where if you put in an outlier, it warns "hey, that number you just entered is 10x the other thousand and one numbers in that column, you might want to check it."

With this model applied to our service, human operators would be responsible for answering questions. The interface they type into might provide some guardrails around length of reply, and might prevent them from including offensive language or committing a HIPAA violation.

The helper - The human does the thing, aided by the machinery. A classic example is narrowing down 100 choices to the likeliest 10. That would be helpful convergence. Or, a canonical example in healthcare being a radiologist assisted by AI to say "hey, I think you should look again at that scan, it looks like these other tumors I've been trained on" - in this case, helpful re-divergence after a human might have converged too quickly.

Here, in our service, human operators are still answering questions. Their interface shows them likely answers, previously accepted answers, or otherwise points them towards papers where they might find the answers. Ideally they would usually use the automated help but in rare cases would use their judgment to go outside the suggested responses.

Autonomation - https://en.wikipedia.org/wiki/Autonomation - Here the machine does the thing, with a human there to detect edge cases, take over from the machine when needed, and ultimately improve the system.

In this case, our service operators would watch questions come in, and see machine proposed answers on their screen. There would be a human-friendly-timescale pause, let's say twenty seconds, during which time the operator would have an opportunity to "stop the line" and prevent an incorrect, offensive or otherwise undesirable answer from being sent.

Full automation - Here the machinery does the thing unsupervised, usually (hopefully!) with heavy post-hoc observability. This sounds frightening but it's actually extremely common. Go to Google and type a search. Your results are returned fully automated. Google has observability over failures, but there's no humans involved in each resultset.

This last model would look a lot like Google, or frankly most popular sites where you're searching for a thing (Amazon, Airbnb, Door Dash, etc). Answers are shipped automatedly to the user, with operators reviewing logs, aggregates, complaint reports, etc. This is really hard. This is why search is so hard. All the above models take longer than our expectations of a web application. Autonomation might be the most frustrating one because it's possibly the best, but it can't operate at the speed we expect and it's impossible to scale wide.

There are probably a lot of markets where the answers are valuable enough and the application narrow enough where autonomation is not just possible, but the preferred model.

posted in Artificial Intelligence


My Writing System For 2023

When COVID hit in 2020, my desire to write went out the window. Except, that's not true. I've been writing as prolifically as ever these last three years. Several thousand words a day, at a minimum. What went out the window is my desire to publish anything publicly. I've been here in my tower, doing the work (remotely), and then using the back and forth of conversations or the timelines of the workplace as my forcing functions to ship. In private. Private spaces like slack, emails and group texts have gotten the best of my words and wisdom for the last three years. And I'm curious why.

I'm not sure why. Fatigue? I'd made a point of either giving a talk or publishing something longform every year since 2014. After seven years of consistently shipping in public, maybe I just needed a break.

Maybe the why will come to me. Or maybe it won't. Water under the bridge, either way. It's 2023, and I'm feeling the urge to start shipping in public again.

One thing I know for sure after nearly 46 years of living with me: If I'm going to do a thing, I need a system of doing to wrap the doing of the thing in. Otherwise the thing happens in fits and spurts and at the whim of my moods. Which means it's probably not going to happen.

Here's the system I've come up with to start 2023 with. A lot of it is stolen from Jerry Seinfeld (you know, the comedian), and specifically from this interview he did with Tim Ferriss. If it changes at all during the course of the year, I'lll come back here and edit this post.

1) Cultivate space for having ideas. I do this naturally at this point in my life. One trick that I've found recently is going on walks either first thing in the morning or after a couple hours of intense focus. This is a case where one thing you're trying to do - get 10,000 steps a day because that seems to correlate with me having better days - feeds into something else. It feels like that happens more and more in my life. Anyway. There's something about walking through the neighborhood at a medium pace that makes it perfect for having ideas.

Besides walks, I find long drives and conversations with old friends to be other great idea hatchers. Both can be challenging though with regards to the next step:

2) Capture those ideas. This sounds obvious, but it's not. You have to capture the idea in the moment when you're on a walk, or it might run down your pantleg and into the sewer when your phone rings, or an important text comes in, or you get back and there's a situation at home or work. Lots of people use pocket notebooks. I use Evernote on my phone, mostly because I've been using Evernote for ~15 years now. If I was starting today, I would start with Notion.

The best best situation for me is going for a walk with my laptop in my backpack. I live in a neighborhood with lots of coffee shops, I'm never not within four or five blocks. Fifteen or twenty minutes is usually all it takes to get a really good draft of something.

In the worst case, I might wait until I get home, and then it's a race: Can I get into a quiet spot that's not my office and doesn't have anything that needs my attention for the five minutes I need to scribble down some bullet points.

And that's it for divergence: Having a lot of ideas, capturing most of those ideas, and maybe somewhere in there organizing the ideas to some extent with folders or tags or whatever. Or not. Organizing can be overdone. Anyway and either way, it's time to converge. This is where it gets hard...

3) Edit. Editing is painful. When I taught creative writing, I tried to focus my units on the editing process. Opinion: Having the ideas and writing them down is the easy part. It makes you feel like a writer. You can look at your notebook or your files on your devices and think, wow, look at all these words. What are those words worth? Maybe a lot, if what you're trying to do is create an identity as a writer for yourself. On the other hand, if you want to be read and make an impact with your words? Not a whole lot, at least until you edit them.

My editing process for 2023: Schedule it. On a calendar. This is the part that I really stole from the Jerry Seinfeld interview. This is also really painful for me. My work week as an engineering leader is largely calendared. And then there's all the chores and appointments and such in my personal life, and those are calendared as well. Why do I want to take one of the few things that I enjoy for the sake of doing it - writing - and put it on the calendar as well?

A: So it gets done.

Editing is so painful that if I don't put it on a calendar and make myself do it, it will not get done.

What happens during editing? There's a reason Jerry Seinfeld's new book is called Is This Anything?, it's because that's one of the primary goals of editing: questioning whether these raw ideas that you have are in your grasp, in your target zone and valuable enough to share. The answer to all three of these have to be yes, otherwise the answer to the question is this anything is No. And when the answer is no, the thing gets thrown out, or rather it gets left in its embryonic state in Evernote. Full stop. And that's painful: letting go of your precious ideas.

Other painful things that happen during the editing process: Even if the idea is good, the original words usually need reworking, refactoring, or just a good rewrite. You have to think about ways of saying things, and whether those ways are clear, concise, and adding up to Your Voice. Finally, you have to polish the thing: Remove typos, forgotten words (my bugaboo), repetitive sentences, anything in the way of The Thing being the gem you want it to be.

4) Ship it. Once The Thing is polished and cleaned up, it's time to publish. Publishing should be dead simple: Take the finished piece, convert it to a blog post, push Publish. And that's it. Publishing is a step because publishing is 10% doing that, and 90% celebrating. Yay! I did the thing. All that pain has paid off.

5) Point people at it. The last step is the one that, sadly, I'm the worst at. It's talking about and referencing what I've written such that other people find it and read it. I'm just lousy at it. If editing is painful, then this thing that I guess is called marketing is torturous. I love scaling products massively, but when it comes to sharing my wisdom and experiences, I seem to prefer a smaller audience by nature.

I share the above as a warning. May you not share my weakness! Go forth and share with the world. And steal the rest of this guide, while you're at it. Or at least go listen to the Jerry Seinfeld interview.

posted in Writing


Communications Skills For Leadership Roles (that they don't teach you in school)

How to listen very, very well such that you understand the speaker's point of view, and they feel heard and valued.

How to tell someone that you - as the appointed decision maker for a specific thing - heard and understood their point of view, and nonetheless that your decision is in favor of a competing point of view, without making it personal and without demotivating them to form their next point of view.

How to signal fuck off, you're wrong with regards to this one specific, situational issue without harming the relationship.

How to say hey can we talk about this first, and I'd like you to listen and consider my side before you make your final decision without signaling that you're whining or insubordinate.

How to cultivate interest in other people's lives, get to know people on a personal level and even "make friends at work", without letting yourself fall into the trap of cronyism / nepotism / etc when it comes to job-related situations.

How to hold back on expressing points of view that are not wanted, needed, fully fleshed out or invalidated by evidence that you're for whatever reason discounting or ignoring.

How to be consistent in your decision making and communications, even when you don't feel like it, are sick, are stressed, are depressed, it's raining and grey outside, a big weekend trip is on the way and you're checked out.

How to signal that you're angry or frustrated or that the current plan is a bad one without having to say it out loud.


There are others, these are just a few that came to mind after a friend asked me "So I think I know all the tech stuff, and the people stuff, and the process stuff, what else do I need to know about becoming an EM?"

In my opinion, if you're very good at this kind of stuff, you can be a baseline C- performer as a leader, even if you're lousy at the other aspects of management and you don't know the field you're in at all.

Also in my opinion, if you're not good at this kind of stuff at all, no amount of skill or talent at the other aspects of management will elevate you past a D+ as a leader. Maybe you could get an A for a little while. Six months or a year. Over time though, your people will despise and undermine you, and your peer managers will undercut and overwhelm you.

posted in Dimensions


Areas and Distances

Went from Portland to Palm Springs for this year's winter break. 1,070 miles. As compared to Paris to Naples, about the same distance. Or Paris to Lisbon. Same idea: The cold North to the warm South in about 1,000 miles.

1,000 miles north to south-ish is about 10 degrees of latitude. Ish. It's actually more like 14 degrees if you went straight north to south, but the most interesting site-to-sites seldom follow straight lines. From Paris, it's south and west to Lisbon or south and east to Naples. From Portland, it's south and a surprising distance east to Palm Springs.

And then there's San Francisco to Portland. Which we just did, after doing Palm Springs to SF. 630 miles. Further than Marseille to Paris, for example. It's roughly Barcelona to Paris. You stopped in Barca on the way back from Lisboa.

Denver is further from Portland than Palm Springs. 1,200 miles!

The West is huge.

California is Italy sized. Or, Italy is California sized. Also, California is Japan sized. All of these are rough approximations. Directionally accurate while being factually incorrect.

Also, density is totally different. Italy and Japan are uniformly filled with people relative to California. California is like two huge populational splats and one long streak down the middle, and the rest is empty. Relatively speaking. People live everywhere. Even Death Valley.

Oregon and Washington together are roughly France sized, moreso if you give a little of Idaho and call it Cascadia. Either one of them is the size of Great Britain. Again, population density being different.

Being home in Portland reminds me what a small city Portland feels like. I can drive anywhere in Portland in 10, 15 minutes max. Including parking. Try going from the Embarcadero to the Zoo in SF. Better book an hour. Much less getting around the rest of the region, SF to the East Bay. The South Bay. The Bay Area is like a small country. Ditto and doubly so Greater Los Angeles, especially if you include San Diego which isn't included officially but is if you go by look and feel.

All numbers and facts in this post are both right and wrong. They're right at one level of resolution and wrong if you're looking for exactitude. I'm finding being able to hold the two ideas of correctness in my head at the same time - something being right on one level while being wrong on another - increasingly valuable in the 20s, and trying to deliberately practice it when I can.

posted in Geography