More on this book
Community
Kindle Notes & Highlights
by
Tanya Reilly
Read between
March 4 - March 5, 2023
I’m always suspicious when a brand-new project already has a design document or plan, and even more when those include implementation details: “Build a GraphQL server with Node.js to…” and so forth. Unless the problem is really straightforward (in which case, are you sure it needs a staff engineer?), you won’t have enough information about it on day one to make these kinds of granular decisions.
If you’re creating a design where it’s difficult to articulate the goals (or if the goals are just a description of your implementation!), that’s a sign that you haven’t spent enough time in this exploration stage.
Team members may fixate on smaller, less important aspects of the project or niche use cases, or expect a different scope than you do. They may be using different vocabulary to describe the same thing, or using the same words but meaning something different.
Be open to existing solutions too, even if they’re less interesting or convenient than creating something new.
If there’s a solution that means your organization has fewer things to maintain after your project, weigh that up when you’re choosing your approach.
How can I hook this concept onto their existing knowledge?
a language shared by the developers of a system and the real-world domain experts who are its stakeholders. Inside a company, even very common words like user, customer, and account may have specific meanings,
That’s because it’s very difficult to have many people achieve something together without shared understanding, and it’s hard to be sure you have that shared understanding without a written plan.
humans aren’t great at paying attention to all of the things. As Atul Gawande, author of The Checklist Manifesto: How to Get Things Right (Picador), says:
Gawande argues that using a checklist helps us talk to each other, avoid common mistakes, and make the right decisions intentionally instead of implicitly. A good RFC template helps you think through the decisions and reminds you of topics you
The goals section should explain why you’re doing this at all: it should show what problem you’re trying to solve or what opportunity you’re trying to take advantage of. If there’s a product brief or product requirements document, this section could be a summary of that, with a link back. If the goal just suggests the question, “OK, but why are you doing that?”
The goal shouldn’t include implementation details. If you send me an RFC with a goal of “Create a serverless API to translate the sounds of chickens,” I can absolutely believe that that’s what you’re trying to do, and I can review the RFC and try to appraise your design. But without knowing what actual problem you’re trying to solve and for whom, I can’t evaluate whether this is really the right approach.
What matters is that at the end, your readers should understand what you intend to do and should be able to tell you whether they think it will work.
But it’s a better use of your time to be wrong or controversial than it is to be vague.
Having disagreements about your design doesn’t mean that you need to change course, but it gives you information you wouldn’t have had otherwise.
you could solve this same problem with spreadsheets, would you still want to do it?13 The “alternatives considered” section is where you demonstrate (to yourself and others!) that you’re here to solve the problem and you aren’t just excited about the solution. If you find yourself omitting this section because you didn’t consider any alternatives, that’s a signal that you may not have thought the problem through. Why wouldn’t simpler solutions or off-the-shelf products work? Has anyone else at your company ever tried something similar, and why isn’t their solution a good fit? I have a policy
...more
Technical pitfalls
If you have five users, you can probably individually teach each of them all the arcane rules of your system. If you have hundreds, or more, they’re going to do it wrong; if you don’t plan for that, your design doesn’t work.
If your project is a veiled “rewrite from scratch,” be honest with yourself and admit it.
Speaking of operability, if it’s going to run in production, decide who’s on call for it and put that in the RFC. If that’s your own team, make sure you have more than three people (ideally at least six) or you’ll be setting yourselves up for burnout and dropped pages.
come back to the team and say, “I found this problem, that river, these resources,” then we can all together discuss how we want to approach this new information. Then maybe I go out and build a rough bridge over the new river, which the team will own and improve. I provide an opinion or two and remind people of some of the tools they have at their disposal, but otherwise prioritize their sense of ownership over my own sense of code aesthetic.
there’s something only I understand, I’ll do it, but insist that someone pairs up with me. Or if it’s an emergency and I know how to fix it, I’ll do it myself and explain it later. Or I’ll write the code to establish a new pattern, but then hand it off to someone else to continue implementing it. That way it forces knowledge sharing.
If you’re reviewing code and changes, be aware of how your comments are received. Even if you think you’re relatable and friendly, it can be intimidating for early-career engineers when a staff engineer comments on their work.
you’re the most senior person on the team and you’re sloppy, you’re going to have a sloppy team. (I’ll talk more about being a role model in Chapter 7.)
Have you ever heard someone talk about a “watermelon” project? They’re all green on the outside, but the inside is red. If your project is stuck, don’t hide it: ask for help.
Something will always go wrong. Maybe you realize that a technology that’s been core to your plans isn’t going to be a good fit after all: it won’t scale, it’s missing some table-stakes feature, or it’s got a licensing condition your legal team has absolutely vetoed.
As the person at the wheel, you’re accountable for what happens when your project meets an obstacle. You don’t get to say, “Well, the project is blocked and so there’s nothing we can do”: you are responsible for rerouting, escalating to someone who can help,
Whatever happens, make sure you keep communicating well about it. Don’t create panic or let rumors start. Instead, give people facts and be clear about what you want them to do with the information.
Some people really resist asking for help. It feels like failure, maybe. But if you’re stuck and need help, the biggest failure is not asking for it. Don’t struggle alone.
Write things down. Be clear and opinionated. Wrong gets corrected, vague sticks around.
wrote a talk once where someone left no comments on the entire 83-slide deck except to suggest a replacement for the bikeshed picture I’d included on one of the slides. True story! I don’t think they were being ironic.
A surprising number of projects are one small change away from succeeding, one quick modification away from unlocking a new opportunity, or one conversation away from consensus. With your organizational privilege, relationships you’ve built across the company, and ability to see around corners derived from your experience, you can often shift a project’s outcomes by investing the smallest ounce of effort, and this is some of the most valuable work you can do.
Start by understanding why the other team isn’t moving. Do they not understand what’s needed? Is something in their way? Understanding means talking to each other. If DMs or emails aren’t working, take it to a synchronous voice conversation–yes, this means a meeting. If the team is hard to reach, going through back channels might help: hopefully you’ve built a bridge with someone on or near the team. (See Chapter 2.)
When you’re waiting for a decision from someone else, it’s tempting to think of their work as easier than yours. They just need to decide what they want, right? Then you have the actually difficult work of building it. I’ve seen this bias a lot for decisions that need to come from outside engineering. “Why won’t the product team just…?” As with many uses of the words “just” or “simply,”
As a result, we had little sympathy for people who came in hot and angry about why we hadn’t done the thing they’d told us about only a few hours ago. Our team motto became “lack of planning on your part is not an emergency on mine.”
you really need to skip the queue, try asking. Be as polite and friendly as possible: you’ll get better results by apologizing rather than yelling at the busy team.
The reasons your colleague gives you for being blocked aren’t necessarily the real ones. The person could be intimidated, stuck, or oversubscribed.
When someone is having trouble getting their work done, there are some ways you can help. Let’s be clear: you’re not this person’s boss or therapist, and it’s not your role to fix their procrastination.
As they write: “A good Three Bullets and a Call to Action email contains (at most) three bullet points detailing the issue at hand, and one—and only one—call to action. That’s it, nothing more—you
Help them, but try not to take over.4 Ask questions, answer questions, and help them find their way.
escalating doesn’t mean complaining: it means asking for help. If your colleague is blocked because they’re working on something their manager thinks is more important, for example, talking to that manager may be the only way to adjust the priorities.
Many engineers cared about the architecture: Geneva’s working group to discuss the problems drew many participants. But the challenges were too big for anyone to solve as a side project.
Since you’re the person most interested in its success, don’t be surprised if other people think that you’re the owner now.
The last type of roadblock I’m going to talk about is when the project needs help from everyone: it’s the kind of deprecation or migration where all of the teams using a service or component need to change how they work. Chances are, not all of them will want to.
One might be broadly in favor of the migration but just doesn’t have time. Another might be opposed to the change: they might prefer the old system, or feel that the new one is missing some feature they care about. A third group might not have feelings either way, but they’re just tired of a constant, demoralizing stream of upgrades, replacements, and process changes that they don’t seem to get any benefit from.
The narrative of a migration can get lost, and I’ve sometimes heard a migration framed as “that infrastructure team just wants to play with new technology” when the reality is an immovable business or compliance need that infrastructure team doesn’t love either. Equally, I’ve heard “that product team doesn’t care about paying down technical debt; they only want to create new features,” when the team in question has already spent half of the quarter reacting to other migrations and are desperate to get started on their own objectives.
Understand both sides and help tell both stories.
Try to make the new way the default. Update any documentation, code, or processes that point people toward the old path. Identify people who might encourage the old way and ask for their help.
One approach I’ve seen is to keep the old way working fine so long as new users write “i_know_this_is_unsupported” or similar as part of their configuration.
Are you really the first person to ever solve a problem like this? Look for what other people have done, internally and externally.
