Jonathan Maltz

Why I Write Weekly Notes

2026-02-01T00:00:00+00:00

I have kept a weekly (or bi-weekly) Confluence blog at Stripe for the better part of 4 years now. Every once and a while people ask why I do that. Here's what I tell them.

It helps in performance review season: It's hard to remember everything you did when performance review season rolls around. Having a weekly blog of your work helps you easily catch up on documents I wrote, decisions I drove, and overall successes.
It allows me to shout people out: I want to make sure people know that I saw the fact that they did good work and I really appreciate it. Tagging people in a weekly blog post via Confluence is a great low-key way to say "I saw you and enjoyed what you did". It also helps me elevate neat things that I think are valuable to lots of people. I try to be especially mindful of doing this with more junior engineers or underrepresented folks.
It helps create ambient awareness of my work: My interests tend to be pretty broad. Broadcasting notes creates awareness of where I'm focusing so that others can find me and potentially either help me out or we can work together to connect our work into a coherent whole. In other words, it helps increase my luck surface area
It helps me organize my thoughts: Writing is thinking. Good ideas don't emerge from my brain on the first try. That's not how my brain works. I need to process a lot of thoughts out loud or at my keyboard in order to get all the messiness straight in my own brain. By keeping a weekly blog it gives me a place to dump down those initial thoughts and sketch out rough drafts to refine them. This helps me get to a clearer final story. I also like to think it helps others see that staff engineers aren't some impossibly brilliant people who come up with things out of thin air. We're humans who bumble through problems to get to the right place, just like everyone else.

So far those work for me. The habit is valuable enough for me to keep it up for a few years. Maybe it will be useful for you too.

Changing Process While Moving To Shipping Phase

2025-01-20T00:00:00+00:00

I oftentimes talk about projects existing in three phases: meetings phase (defining the scope), building phase (building it) and shipping phase (converging and flipping the thing on). Transitioning between these phases is always a little chunky for different reasons. Recently I've noticed that I do a set of consistent things when moving between building phase and shipping phase. These generally feel right, so I'm probably codifying them.

The three things you should do when moving into shipping phase on a large project are:

Make a dashboard that counts the number of tickets required to launch your first user-visible deliverable. While you're in building phase it can be easy to lose sight of exactly how much work is remaining in order to get software into the hands of users. By making a dashboard with all outstanding tickets you can give yourself a very clear velocity + progress tracker on "how far are we from shipping". "Number of tickets closed per week" is a pretty coarse metric, but it's often good enough to set more accurate estimates.
Setup regular bug-bashes. During building phase it can be easy to build a bunch of pieces but not have confidence that they actually deliver a coherent experience for users. To combat this, I'll setup weekly bug bashes for the whole team to test features end to end. This helps people get a really visceral feel for "where's the system at end-to-end" rather than just "is my feature working". It also encourages you to find rough edges in test setup and rollout which can help smooth out your actual launch.
Ensure that each part of the system has an end-to-end owner. In building phase it can be easy to think "horizontally" through the system and make sure each component works. Oftentimes as you enter into shipping phase you need to start thinking about the system end-to-end. In this world it can be valuable to start to have people owning complete slices of features if they don't already.
Write up the actual plan to test and rollout your software. Similar to the bug bashe point, it can often be easy to miss "is it possible to rollout this thing as a single unit". You'll want to write down a rollout plan to ensure this is possible.

Doing these things doesn't always ensure that the process of shipping goes smoothly, but I've found that they generally help. So next time you're entering shipping phase, consider keeping a couple in your back pocket to ensure you launch successfully.

Flashcard prep

2024-11-02T00:00:00+00:00

This is a little flashcard game I made to help my wife prep for the USCIS citizenship test.

The game

Question:

Answer:

Managing Documents In a Hybrid World

2023-04-25T00:00:00+00:00

When teams shifted to remote + hybrid work, they also needed to adopt a much greater emphasis on having a written culture. On our team, this came with an additional problem: we ended up with so many documents it was hard for us to understand which ones were important/unimportant. Shortly after that, we had a new manager joining our team and he gave us a few tools to manage this document explosion.

Tool #1: Clarify The purpose of the Document Via Emojis

The first challenge tackled was that documents take on many purposes. Without any clear signal for “this is what this document is intended to do” it was hard for readers to differentiate “here’s a half-baked idea that I’d love 30% feedback on” from “this is a design document that we’re now implementing”. To fix that, we created a simple emoji-based taxonomy for all of our documents. The system worked as follows.

A 💻 represented a design documents, and were assumed to express “here is a thing I am planning to build”.
A 👀 represented a “validate my perspective” document. These could be anything from “Here’s a wild idea I had for a team process change” to “a rough cut of what our next quarters OKRs should be before we go into planning”.
A 🌅 represented a vision document. These could either be technical vision or product vision. Either way, they were not assumed to represent exactly what we were build, but directionally were we were going.
A Gavel emoji represented a decision document and expressed “here is some decision which needs to be made outside the scope of a design document”. It could be a technical decision (“how will we scale the foo service”) or a team process decision (“how frequently will we hold sprint planning”)
A 🗒️ emoji represented meeting notes

Taken together, this simple taxonomy helped readers who stumbled across some random document clarify “how should I reason about this”.

Tool #2: Store All Documents of a Particular Type In a Folder

Once we had a taxonomy, we then created a simple system for organizing documents according to their type. We started out by organizing according to type (all 👀 would go into one folder, 🌅 into another, etc.) but we found this to be a little overwhelming as time went on. Instead we moved to a simple format where largeish projects would have their own folder where all documents lived (often with a single “hub” document as an anchor) while other documents (small design documents, unrelated "validate my perspective documents", etc.) would go into the shared folder.

This proved to be very helpful because we found document search in most tools works ~75% of the time. We often found ourselves knowing “oh yeah, I had a gavel document for that somewhere” or “I think someone wrote a vision document for that” but not knowing the exact search incantation to find it. By having a simple folder structure to store documents we were able to save a lot of time hunting for documents. This also played nicely with icons, as we could easily look at any document without a folder, look at its icon, and know where it needed to be moved to.

Tool #3: Clarify Status at the Top of Each Document

After those two changes, we adopted was having a simple “status” box at the top of each document. This status box was a one cell table which contained the author, the date the document was updated, and a status of the document (whether it was early draft, ready for review, or just some rough scribbles on a page). In practice it looked like this.

Author: Maltz
Status: Very early draft. Believed to be directionally correct, but not ready for feedback yet.
Last Updated: Apr 25, 2023

By clarifying when a document was ready for feedback and when it was last updated, readers could understand what level of feedback was appropriate for the current document status. This helped us in a couple of concrete ways:

It prevented some classes of thrash where someone would write a spicy “validate my perspective” document, share it with a couple of people, and then forget about the document. Someone would then find the document 6 months later and get heartburn that some big change was happening.
It prevented people from finding a design document that was 30% complete and giving it fine-toothed-comb feedback even when it wasn’t ready for that.

In both of these cases, the presence of a simple “status” box helped readers contextualize “how much should I care about this” and “how should I engage with this document”.

In practice we didn’t enforce a strict policy on keeping these fields up to date, but documents which tended towards adoption would get the fields updated naturally just through sheer number of eyeballs.

Tool #4: Clarify expected approvers when necessary

Once we had this taxonomy, we encountered one other problem: for documents which were trying to drive towards a “decision” (i.e. Gavel documents or design documents) it would be unclear who was responsible for actually saying “this decision has been made”. We solved that by adding a small section at the top called the “Gavel Block”. This was a simple list of people who needed to approve and could check-off their names or add blocking feedback.

This practice was again simple but very helpful for clarifying the RACI Matrix around a particular document. If your name wasn’t on the gavel block, you didn’t have to review. Similarly, if you came through with feedback and wasn’t on the gavel block, then the author could easily clarify “do you want to be on the gavel block” or “is this non-blocking feedback”.

These tools didn’t solve all of our challenges related to having a heavily written culture, but they did help our team operate substantially more effectively. Plus, they were lightweight and easy to adopt. If your team is struggling to sift through a pile of documents they’re probably worth a try for you as well.

A big thank you to Marc Weil who both reviewed a draft of this and helped us implement these changes!

A Hub and Spokes Model for Documentation on Large Projects

2023-03-30T00:00:00+00:00

As projects grow it can be difficult to keep track of all of the documentation associated with them. Between product requirements documents, design documents, meeting notes, and architecture decision records it can be easy to find yourself lost in a forest of Google Documents trying to find that one document which has the information you need. A while ago a friend told me about a simple model to manage this complexity on large projects, something he called "the hub and spokes" model of project documentation.

How's it work?

The basic idea of the hub-and-spokes model is simple: you create a central document (a hub) which serves as an entrypoint into the project. Oftentimes this is some central "why are we doing this thing" document like a product requirements document or a project brief. You then use that to link out to smaller documents (notes, decision logs, scoping documents) which describe a more focused topic. Within the more focused document you include a backlink to the "hub" so that folks can walk up the stack.

This approach isn't necceary in tools like Confluence which automatically create a documentation tree, but they take a little more discipline when you're just using a raw documents tool like Google Docs.

How Teams Change At Different Sizes

2023-02-26T00:00:00+00:00

During my career I've had the chance to work on teams of a lot of different sizes. During that time I've come to realize there are really six "buckets" of team sizes. At each bucket, ICs + team leads need to operate a little differently in order to be successful within those teams. The sizes are:

1 Person: Do what you want, YOLO
2 → 3 People: An ideal small squad. Team can stay in touch with daily slack-ups and maybe an ad-hoc meeting when necessary. In a remote world you probably need a weekly sync, but in-person that may not be necessary.
4 → 5 People: The size at which "which get everyone into a room" is a productive strategy whenever you have a challenge. This is the size at which one seems to be able to tech lead and manage as well. You probably need a weekly sprint planning meeting to get on the same page because you've split into two squads. This also conveniently lines up with the first of Dunbar's numbers.
6 → 9 people: The platonic team size. One manager, eight engineers, maybe a product manager. Order your two pizzas, appreciate the fact that you have a good balance of size and redundancy, and execute away.
10 → 12 people: Team has likely become a little sprawling but may not have an exact obvious cut point. Often characterized by needing to share lots of context between people because of the broad scope, and a manager who is being pulled in a bunch of directions. Team is strained, but not breaking. Chances are ICs will be doing some "gap filling" to make sure the team communicates well here.
13+ people: GG. This isn't even a team anymore; just an overwhelmed manager and a bunch of sub-teams who secretly need to break off, but they can't, either because there's no one to manage the right sub-teams or the boundaries between "what should be the sub-teams" are not clear.

Of course, these aren't THE ONLY team models that exist, but I find them to be generally useful baseline rules when thinking about "how should I operate within a team"

When Should You Spend Time on Technical Vision

2022-12-04T00:00:00+00:00

One of the challeging things about being a technical leader is knowing how much time to spend on big-picture vision setting vs. writing code and solving the problems of today. Spend too much time on vision setting and you may start designing solutions which are disconnected from reality. However, if you don't spend enough time on vision your team will sputter over the long-term. Over the last couple of years I've found a few heuristics to apply which let you know when it's time to jump into "vision setting mode".

What's Technical Vision

Before digging into when you need to spend more time setting a technical vision, it's important to understand what a technical vision looks like. A technical vision can take many forms, but it's most often an aspirational document (frequently ~2 -> 5 pages) which outlines an ideal future technical state that a team will achieve over the next 18+ months. Technical visions are useful as an anchor point in the cone of strategy to help tie-break day-to-day technical decisions. They rarely end up being exactly correct, but they can also serve as a useful tool to elucidate any large gaps in what your team is currently building and help the team take a first step towards fixing those gaps.

What are The Signs You Need To Spend Time Clarifying Your Technnical Vision

All of those things seem great, so why not just spend all of your time on technical vision? Unfortunately, creating one comes with a cost. The first cost is obvious: drafting and building consensus around a vision takes substantial amount of time from the author and reviewers to make sure the vision is directionally correct. Vision documents also come with a cost for the team. Once drafted, you actually need to get the team to shift course and use that vision in their day to day decision making. While this is useful, it also takes time, and can lead to a feeling of whiplash if the team feels like they're changing their north star too frequently. So, what are some cues you can use to know that it's time to pay this cost and draft a technical vision?

Case #1: When people are constantly disagreeing over small changes

One of the first signs that the team needs a clearer technical vision is if the team is constantly getting bogged down in small design decisions. While some design push-and-pull is to be expected on code reviews and design documents, the team should spend most of their day-to-day time discussing questions on the margins rather than constantly re-litigating core questions about what you're building.

If you start to see the team having these "re-litigate the world" discussion frequently, chances are there's a few key underlying architectural decisions which the team has not investigated and decided upon. Drafting a technical vision can help bring these disagreements to the forefront and allow the team to come to a consensus about how to architect a solution to these problems. While the vision won't magically solve all design disagreements, having an agreed-upon north star should prevent the team from churning on the same design issues every code review.

Case #2: When team discussions become sprawling

Sometimes teams will encounter a situation where they can make design decisions effectively, but it feels like many decisions are time-consuming because they require "inventing the architecture as they go". In these situations, the problem isn't so much disagreement so much as confusion about how all of the pieces of the system should fit together. This means that simple questions like "how should we deploy this thing" becoming sprawling discussions without about "well how do we even want to use Jenkins here". While some amount of this type of "zoom out" thinking is useful, if you find it's slowing down the team it may be time to invest in clarifying your technical vision.

Resolving vision gaps in these cases is often slightly different than in Case #1, as there may not be any core disagreements to resolve. Instead, it may just be a case of a team having differing expertise, and no one has yet stitched all of the moving pieces into a coherent narrative. As a result, in these cases may have less disagreement-resolution, and more stitching-together disparate pieces of context into a coherent whole.

Case #3: When you've hit a local maximum

Sometimes it becomes clear that your current way of doing things just won't work. Maybe you're constantly firefighting bugs in your infrastructure, or maybe your customer requests are becoming progressively harder to implement. Regardless of the symptoms, if your team is churning through problems as best it can, but it seems like you're stil falling behind, chances are you need to do a clarify your technical vision and chart a path to something fundamentally better.

These types of technical vision can feel a little different than ones created for the other two cases. They will still chart a course to a glorious future, but they also need to come with a concrete first step ("we will start on this vision by doing X to solve our immediate scalability needs") which helps the team out of its current situation.

These three cases aren't the only times teams will need to clarify their technical vision, they do represent three common cases to look out for. So, if you find yourself repeatedly bogged down in the same technical discussions, struggling to fit together a number of disparate design decisions into a coherent story, or just stuck in a technical rut, it's worth asking yourself "does our team have a clear enough vision about how to solve this problem" and filling that gap if not.

Collaborating Effectively By Focusing on Understanding

2021-05-16T00:00:00+00:00

A while back a friend gave me some important, but hard to hear feedback. She told me something to the effect of "you always assume other people are wrong, and it limits your ability to collaborate with people." I'd always considered myself a strong collaborator, so hearing that I actually had a long way to go was humbling. For the rest of the year I worked on breaking this habit with a simple mental framework: whenever I'm surprised by something, assume that the other person has already done what they believe to be the exact right thing." This simple idea was incredibly powerful for pretty much everywhere, but it's most handy in a few situations.

Project check-ins

When leading a project, it's common for something to take longer than expected. It's my job as a project lead to figure out how to unblock that. One way to do that is just ask "Hey Albert, what's the status on your piece of this project?". This is fine, but it also communicates "Albert, you have done a bad job on keeping people up to date on what's happening, and now I'm worried about it." It also doesn't put me in a position to actually help with anything that's going on.

Alternatively, I could ask "Hey Albert, how is your piece of the project going? Is there any way I can help move this faster?" Suddenly my question is no longer adversarial. Now I'm trying to figure out if there's any way we can move the project forward together. Maybe Albert will say "nope, this particular bug is really kicking my butt" and I can offer to pair, or maybe he will say "I keep getting random asks from another team, and that's distracting" and I can work with them to prioritize asks appropriately. Whatever it is, by explicitly offering to help rather than "just checking in" I've put trust in Albert and opened the door for a rich dialog about how we can effectively collaborate.

Design documents

Oftentimes I'll look at a design document and think "this decision seems wrong, they should be doing it another way". The naive way to approach this is to say "Samantha, this approach seems unscalable, we should do a different approach". However, this approach starts from the asusmption that Samantha is wrong and has made a poor decision.

If we instead start from the assumption that Samantha has made the right decision, our feedback looks like "This approach is surprising, as it seems like it would be less scalable then ${SOME-OTHER-APPROACH}, why are we doing things this way?" Suddenly my feedback isn't adversarial! Samantha can now say "That's a good point! I'll fix that.", or she may say "we considered that, but abandoned it for XYZ reasons". Whatever the answer, we can discuss it from a perspective of mutual understanding rather than oppositional disagreements.

As with all things this approach isn't perfect. There are sometimes where you just need to come in and drop the proscriptive-hammer and say "this isn't happening". Communicating this way also takes a little extra time, and may not be ideal for people who are used to a more direct mode of disagreement. However, I've found that taking a default posture of "this person isn't wrong, I just don't get it yet" my conversations are much more productive and collaborative.

Some thoughts on "organizational neutral"

2021-04-03T00:00:00+00:00

Recently I had a shower-thought about the concept of "organizational neutral". "Organizational neutral" in my mind can be contrast with "Organizational fifth gear". You know you're in fifth gear when people are trying to pour gas on whatever thing you're working on. Users are flooding you with feature requests, your part of the org is getting as much headcount as you want, and people are generally very excited about what you have going on. The problem when you're in "fifth gear" is that you need to pick a generally correct set of things to work on and make sure that people are not stepping on each other's toes too much (there's probably a separate version of this for hypergrowth, where you just point a mass of people in the generally right direction and pray).

The other opposite to "organizational neutral" is "stopped" or even "reverse". This is what happens when you keep suggesting ideas and people go off and do the opposite. Your manager starts having very direct conversations with you saying "don't do that" and you aren't getting any traction. When you're in "stopped", the key is to recognize the signs, stop what you're doing, and re-orient to figure out how to do more correct things.

Organizational neutral is neither of these. It's a no-mans-land between "let's double down" and "stop doing what you're doing". No one is telling you to stop, and you're occasionally getting positive signals, but people aren't banging on your door to buy whatever it is you're selling. Getting out of neutral is hard, because there's friction in almost any direction. You need to apply focused energy to get out of neutral, but it's unclear where to apply that energy. You don't have anyone in the organization telling you where to go, and it feels like making anything real happen requires much more energy or staffing than you have available. These are often problems shaped like "cultural change", which can't happen just by flipping a switch in code.

I think the key to us getting out of neutral is to very publicly do cheap things that didn't require any additional permission. Some things that don't require anyone's permission include:

Holding meetings
Giving presentations
Writing prototypes
Collecting lots of data
Writing documents

By contrast, things that do require permission include:

Staffing long-running projects
Changing team process

The name of the game is been to do things that don't require anyone's permission, show that they matter to decision makers, and then gain permission to make larger changes based on our successes. The other key part has been doing all of this very publicly. When you're trying to get out of neutral, one of the biggest challenges is to get other people to care. Taking an effort from 1 → 2 people gives you WAY MORE than a factor or 2 speed up, or at least it feels like it does. Being incredibly public with the work that we're doing + how to find us increases your luck surface area; it doesn't guarantee that you'll happen to stumble across a partner-in-crime, but it certainly makes it much more possible.

So, how do you get out of "organizational neutral". Place lots of very public small bets by doing things that don't require any permission. See where you get positive feedback and double-down on those areas to recruit allies.

Some Thoughts on Rules Engines

2021-02-21T00:00:00+00:00

Spend enough time working with domain experts on a problem and someone is bound to say "we should build a rules engine to solve this problem." Often this comes along with the goal of letting domain experts express rules themselves rather than having to evolve engineers. However, once you start to dig into this problem you'll discover that "rules engine" can mean many different things to many different people.

I've seen this problem a few times over the past couple of years, and I've come to think it's useful to break down your rules engine across a few important axes. Doing this will allow you to have clear discussions on what problems you need to solve and what you need to build to solve them.

The questions

What data do your rules have access to? Do your rules need to arbitrarily grab data from a database, or are there a set of well-defined features that people need to express their rules?
When will your rules run? Do they run on every request? When some set of known events happen within your system? Whenever a data pipeline kicks off?
What actions will your rules take when they pass? Do they just need to output true/false, or do they need to output some more complex actions? If the latter, what do you do when a set of rules conflict?
How complex are the rules you want to express? Do you essentially want to run arbitrary logic to match rules, or do you have a set of simple if/else conditions that you need to follow?
How do you want to express your rules? Is abstractions in a programming language okay? Or do you need something simpler?

All of these taken together form a set of constraints for your rules engine. If you want to express arbitrary logic over arbitrary data, well then you're probably doing to need to write a business readable DSL or use something like drools. If you can simplify across some dimension, you can probably save yourself some work .

Looking at this in practice

Let's think about how all this works in practice by using a few examples.

Radar from Stripe

Stripe's Radar product has a rules engine which allows merchants to configure how they should handle charges. It answers the above questions in the following ways:

What data do your rules have access to? A constrained set of features that Stripe provides.
When will your rules run? On every charge to your business.
What actions will your rules take when they pass? Block, allow, review, or request 3DS for the charge. Conflicts are resolved by choosing the first rule that decided on an action.
How complex are the rules you want to express? Fairly simple, a few if/else conditions.
How do you want to express your rules? A simplified DSL that any non-engineer can configure.

This approach constrains users across almost every dimension, but the resulting rules engine is simple enough that almost anyone can use it.

FXL From Facebook

At the other end of the spectrum is FXL, a language that Facebook developed for fighting spam. It has slightly different answers to these questions.

What data do your rules have access to? "A Multitude". We don't know for sure, but probably more than the O(10s) of features radar allows.
When will your rules run? Presumably something like "whenever a content creation request comes in."
What actions will your rules take if they pass? They may log requests, block posts, or warn users. Other actions and conflict resolution is undefined.
How complex are the rules you want to express? Seems like they can get quite complicated.
How do the rules get expressed? A hand-rolled language called FXL.

FXL's rules engine gives users more power at the expense of some complexity. The rules are actual code rather than fancy configuration. This creates spam fighting superpowers at the price of it being harder for non-engineers to interact with write.

SQL-Based Rules Engines

Another common pattern is the SQL-based rules engine, which has an example here. The general idea of these is often "our domain-experts already understand SQL, so let's allow them to just write their rules in a language they know." Again, this can fit into our framework.

What data do your rules have access to? Anything in your database.
When will your rules run? Probably in response to a web request.
What actions will your rules take if they pass? Some set of actions defined as stored procedures. Resolution is again unclear.
How complex are the rules you want to express? Not crazy simple, but also not crazy complicated as well. We could probably express some pretty complex stuff in raw SQL if we needed to though.
Hwo do the rules get expressed? SQL statements that follow a well-defined form.

These approaches fit somewhere in between the two approaches above. They seem useful when you want to return a simple classification result, but it may get more challenging if you want to take more complex actions.

Using the framework

I'm not totally sure exactly how to use this framework yet, but it has been useful for me to ask these questions whenever someone says "we need a rules engine." I hypothesize that if you want to keep the expression language simple, you'll need to invest more engineering-time to provide curated data to your rules engine and limit what it can do.

I also imagine that these approaches can be mixed-and-matched for maximum effectiveness. For example, you could have a rules engine which is based on a business readable DSL, and provide some tooling for non-engineers to create for common use-cases. This allows for iteration speed in the common case without sacrificing power when you really need something complex.

Communicating through uncertainty

2020-05-25T00:00:00+00:00

Recently I've found myself in situations where there's no right answer. In these situations it can be hard to know how to proceed and even when you do make some decision, it can be hard to communicate that to a team in a way that builds confidence in spite of the uncertainty. I've recently been watching some great leaders do this, and I've found that doing it well boils down to a few simple steps.

It makes it clear that a decision has been made
It makes it clear that trade-offs have been considered
It describes when/how the decision will be re-evaluated
It follows up

It makes it clear that a decision has been made

In situations with lots of uncertainty there are often lots of different approaches and disagreement about the correct path. Once you’ve made a decision about which path to take, it’s important to communicate that as a decision being made, and not an opinion for further debate. For people used to building consensus this can feel overly dictatorial, but making it clear that a decision has been made often helps the silent majority, and allows you to stop arguing and start getting more data.

It makes it clear that all angles have been considered

Decisions in ambiguous situations are bound to have some dissenters. For many, their natural reaction to things not going their way will be "X just doesn't understand this problem so they’re making a bad decision" or even worse "X is actively out to make my life hard". Both of these erode trust, and you want to prevent these sentiments. The best way to do this is to make it clear that you’ve heard the objections and you still feel this is the correct path.

It says when + how the decision will be evaluated

One of the best ways to get more people onboard with a decision is to communicate them as an “let’s try it” experiment rather than a choice etched in stone. You can do this by describing your approach as a hypothesis being tested with clear criteria and an evaluation date. This is particularly helpful in calming dissenters as it gives them a clear point where the team can re-litigate the issue if this approach turns out disastrous.

It follows-up

Once the decision has been made and it's been evaluated, it's important to follow-up with the results and next steps. This serves two benefits. First, it prevents you from scarring on the first cut and accidentally encoding an ineffective experiment as permanent policy. Secondly, it builds trust so that when you suggest future experiments, people can trust that you're not making a permanent change under the guise of “an experiment”.

You’ll definitely want to follow-up and share out results at the end of your experiment, and depending on its impact you may want to check-in a week or two after the experiment starts, just to let people know that concerns are being heard and small course corrections are being taken.

An Example

To think about how that works in practice, let's consider a common problem. Your team has started shipping more bugs to production. Lots of people have theories about how to fix this, ranging from hiring a QA team to just shrugging their shoulders and saying "bugs are a fact of life". You have decided to try to resolve this by putting a pre-push hook which ensures that code coverage is about 50% for any new pull request. Let's look at how to message that, starting first with the simplest message.

Hey team, just wanted to give everyone a heads up that starting Monday we'll block any pull request which has less than 50% code coverage. Hopefully this will decrease the amount of bugs we ship to production.

This is a fine approach, and it scores well on making it clear that a decision has been made. At the same time, it doesn’t show what alternatives have been considered or how that decision is being evaluated. This may create critiques like: "code coverage is a terrible metric", "this will never decrease our bug rate fast enough", or “a QA team would be better”. The people with these critiques may also have FUD that you’re enshrining a bad choice without considering all angles. Let's think about how to resolve that.

Hey team, as I'm sure you've noticed, our bug rate has been creeping up over the past month, and we've had to roll back a number of our changes in production to prevent serious impact to our users. That's why starting Monday we're going to require that all changes have > 50% code coverage before merging.

We recognize that code coverage isn't a perfect metric for making sure that our changes are high-quality, but we chose this approach because it's quick for us to instrument, and it will allow us to quickly understand the impact of more rigorous testing standards on our development process. This will make it harder to get changes into production, but we have seen that most of our production incidents could've easily been caught by testing, so we believe that by explicitly encoding a minimum testing bar, it can be a good first step to prevent a large class of errors.

Let me know if you have any questions.

This is way better. It still makes it clear that a decision has been made, it explicitly shows people that you've considered the trade-offs, and you've still chosen this path. At the same time, it still may leave people worried that you’re going to encode a burdensome policy forever. We can resolve that by framing it as an experiment.

Hey team, as I'm sure you've noticed, our bug rate has been creeping up over the past month, and we've had to roll back a number of our changes in production to prevent serious impact to our users. That's why starting Monday we're going to start a trial where we require all changes to have > 50% code coverage before merging.

We recognize that code coverage isn't a perfect metric for making sure that our changes are high-quality, but we chose this approach because it's fairly quick for us to instrument, and it will allow us to quickly understand the impact of more rigorous testing standards on our development process. This will make it harder to get changes into production, but we have seen that most of our production incidents could've easily been caught by testing, so we believe that encoding a minimum testing bar can be a good first step to prevent a large class of errors.

As with all things, we're treating this as an experiment. We'll let this policy run for 4 weeks, and then check the number of bugs in production and talk to some developers to see how it's impacting your workflow. We’ll then decide on next steps.

If you have any questions, please let me know.

This final version does everything that the first two do: it clearly communicates the trade-offs and makes it clear that a decision is being made. It also frames the change as an experiment, which makes it feel much more reversible and prevents some amount of re-litigating the issue from people who disagree.

This approach isn't always perfect. Sometimes you just need to make a decision and commit to it for the long term. However, many times you can frame your ambiguous decisions as experiments and communicate about them accordingly. This will lead to happier teams, and hopefully less heart-burn as things change.

Running Design Sprints for Engineering Teams

2020-04-10T00:00:00+00:00

Sometimes engineering teams find themselves in a situation where they're tackling a cross-functional problem with no clear path forward. In these cases it can be challenging for individual teams to break out of their silos and see the global problems, resulting in local optimization while the larger problem remains unsolved. Fortunately, teams can follow the structured process of a design sprint to cut through these problems and quickly forge a path forward.

What's a Design Sprint?

Design sprints are 5 day exercises which product teams can use to tackle an ambiguous problem. Sprints follow a structured process of rapidly gathering context, ideating on approaches, picking a direction, and putting a prototype in front of users. This allows teams to turn weeks of debate into lessons from users.

Engineering teams generally don't need this whole process, but they can steal the first two steps: rapid context gathering and ideating on approaches, to quickly find a path forward for cross-functional problems. All that's required is you follow a structured approach to problem solving.

Day 0: Have a Facilitator Do Some Legwork

Before you try to run a sprint, you'll need a facilitator. The facilitator will act as a guide through the process and ensure that the process moves towards a workable conclusion.

A good facilitator will have enough context on the problem to guide the discussion, but they should not be someone who needs to actively participate in the sprint. Facillitating for 6 hours a day is a full-time job, and trying to both facillitate and participate is a recipe for doing neither thing well. This makes it a good chance for someone to get into the room with decision makers by providing a much-needed skill.

The facilitator has a few jobs leading up to the sprint:

They need to a consistent room for ~8-10 people for 2 days straight. They'll also need to make sure it's appropriately setup. Finding a conference room that fits this profile isn't easy, so it's one of the first things the facilitator should do.
They need to identify 4-6 people who will be actively participating. These people should be experts in their area, have enough knowledge to understand the domains of other sprinters, and be in a position to push forward prioritization of any requisite work post-sprint.
They need to set a schedule of lightning talks and create a consistent slide deck for people to present from. A consistent slide deck may seem like overkill, but it will make sure that the lightning talks on day 1 answer the right questions.
They need to purchase all necessary supplies
They will need to write a sprint brief explaining the problem the team is solving.

The facilitator will also be responsible for sharing and enforcing the No Distractions Policy. This means they'll kindly, but firmly, tell people that they need to leave their phones at the door and not check Slack/email while they're in the sprint room. They're welcome to leave at any time to attend to something, but they just need to do it outside the room.

This is a lot of logistical legwork, but it's important. This will use ~2 engineering weeks of time, and it's their responsibility to make sure it is well spent. Once all of these pieces are in place, it's time to move to day 1.

Day 1: Lightning Talks To Build Context

The first day of the sprint is focused on breaking participants out of their local context and giving them a global view of the problem. This is accomplished with a day of lightning talks covering the problem space.

Lightning talks are ~15 minute talks which explain particular team interacts with the sprint's problem. For example, if the problem is "how can we reduce number of bugs we ship", you may have a lightning talk from an application team discussing how they test for bugs, and a release engineering team talking about how code gets released to production. The facilitator should also include talks from relevant non-technical teams like support or product management to ensure that sprinters have a well-rounded view of the problem. All told, you'll probably have ~10-12 lightning talks.

During each talk sprint participants should capture opportunities through how might we (HMW) statements on post-it notes. Each of these statements will describe an aspirational question the team may want to solve based on that lightning talk. After each talk, participants will put these up on a shared surface. This will serve as the basis for discussion on day 2.

By the end of day 1 you should have a whiteboard filled with problem statements and a team that is now appropriately level-set. Day 2 will be about digesting those and making them actionable.

Day 2: Digest to problem statements

Day 1 was all about collecting a variety of problem statements; day 2 is about synthesizing the global problems. The team accomplishes this by grouping, ranking, and driving towards rough consensus on problem statements.

The first step in day 2 is to group the HMW statements from day 1 into themes. This doesn't need to follow rigid guidelines, but you'll want to physically co-locate similar problems together. Grouping will likely reveal a few large clusters and a number of smaller satellites. The facilitator then should give everyone voting stickers and have them vote on the HMWs they feel are most impactful, allowing duplicate votes if they feel strongly about a topic. This whole process will take ~1 hour and it will reveal a heat map of ideas the team feels are the most valuable.

The facilitator should take this map and find 3 distinct areas for participants to dig into. These problems should be the ones that got the most votes and cut across engineering teams. This will leave out impactful problems which are the domain of a single team. That's okay; if a team already owns a particular problem, their internal processes can likely solve that problem.

Once the facilitator has identified areas, they should spend ~30 minutes on each problem getting the participants to distill it down into a problem statement which everyone can roughly agree on. For example, if you saw statements like "how might we allow developers to test on real data?" and "how might we prevent bugs which only show up on production infrastructure?" you may work with the team to distill that down to "how might we allow developers to safely test their code in a prod-like environment?" This problem statement succinctly captures a global problem which otherwise may have fallen between teams.

Getting perfect consensus will likely be impossible, but if you can get something that people can accept for each problem area, that's a big win. Even if you can't, understanding what's blocking a crisp statement is a big win

Achieving this rough consensus will take the better part of a day, and will likely leave everyone's brain pretty fried. You'll want to spend the last bit of day 2 wrapping up finding any next steps to start making progress on these problems.

Day 3 -> Onward: Driving Forward Results

The two days of sprinting are intense, but they're also only the beginning. They've produced a set of problem statements, but now they need to get solved. Solutioneering is it's own can of worms, but there are a few things you can do to set yourself up for success.

First is the facilitator should broadly circulate notes + takeaways to a wide group of relevant stakeholders. This serves two purposes:

It starts to socialize these problems, so that the wider team can start to form a more global problem understanding.
It helps make sure that you didn't make any big errors. You don't need total agreement on the problem statements, but you want to make sure you aren't making egregious errors.

You should also appoint a directly responsible individual to drive forward solutions. This person will be responsible for making the impossible decisions involved in turning problem statements into concrete proposals for solving any problems. They will work with teams to build define roadmaps and projects as required, and then ultimately getting those ideas prioritized to deliver solution.

Where is this not the right idea?

Running this type of sprint is a great way to get a bunch of shared context and kickstart problem solving, but it's also time-consuming, so you don't want to use it in every case. In particular, you probably don't want to use it if:

You already have a reasonable idea of how to solve a problem, but you need to explore its edges. In that case you may be better served by building a prototype or running a hackathon.
A number of people understand the problem, but it's still not moving forward. A lack of collaboration may not be your biggest problem here, you may have underlying organizational issues that need fixing.
You aren't confident that you can get a DRI responsible for driving solutions. If you don't have the ability to execute, all of the brainstorming in the world won't help you.

However, if your problem does fit the mold of "we need to get people talking and brainstorming", running this process can be a great way to cut through the challenges of cross-team collaboration. It won't immediately produce a solution, but it will quickly give you enough to get started, and that be half the battle.

Raising Problems Without Raising Blood Pressure

2020-04-08T00:00:00+00:00

As you move from owning individual problems to owning projects, you'll often find yourself in a position where you're surfacing risks to your manager or other senior folks. Doing this well can be an art; on one hand you want to stay stay aligned with authority and make sure that leadership is aware of the problems. At the same time, constantly surfacing risks without helping mitigate them can erode confidence in your ability to deliver. Striking this balance can be hard, but can be repeatedly done with the right communication strategy.

Where Do Anxiety and Confidence Come From?

When considering how to do this well, it’s worthwhile to think about building confidence in your ability to deliver. I like to think about this with the two equations:

perceived_risk = perceived_impact * perceived_likelihood_of_occurrence

perceived_confidence = sum(perceived_ability_to_impact / perceived_risk)

These aren't scientific, but looking at them gives an idea of the levers we can use to increase peoples' confidence in our ability to solve a problem: We can

Lower its perceived magnitude
Lower its perceived likelihood of materialization
Increase others' perceived ability to impact it

We'll assume that #1 is outside of our control. There may be reasons to inflate/deflate the perceived magnitude of a problem, but those are beyond the scope of this post. Fortunately, we can manage #2 and #3 by how we talk about risks.

How to influence confidence perception

The simplest way to affect these two factors is to follow a simple rule: every description of a problem contains a description of its probability and either actions being taken or a request for support. This is really easy to do when you've got the problem under control. I like to follow the below template to make sure I get it right.

There's a risk that ${PROBLEM} is going to bite us on ${TIME-HORIZON} at ${PROBABILITY}, we're mitigating this by doing ${ACTION-1} and ${ACTION-2}. How does that sound to you?

This template is nice because it describes the problem without making us seem helpless. It gives the other person a clear anchor so that they’re aware how much they should keep an eye on it. This phrasing also shows that we're aware of the risks, are actively taking steps to prevent them from materializing, and that there’s an obvious path to influence that risk through guiding us.

Sometimes you don't know about the solution up front, and you need to escalate for support. You can still do this in a confidence-building way by saying:

Hey {X} I have ${PROBLEM} and I'm not sure how to solve it. Can you help me brainstorm solutions?

This clearly shows that you've got the monkey on this problem, but you need help figuring out how to deal with it. By including a clear ask for help, you've shown how the other person can impact the problem, which can help control their concerns.

An Example

All of that is great in theory, but how does it work in practice? To consider that let's take a simple example: you've been asked to prepare an estimate that you are targeting to deliver in 4 months. After running the numbers, you find that your estimate range runs 3 - 6 months. This means there's a risk the project will slip its 4 month target. Your first intuition may be to present this as:

We believe the project will take 3-6 months, so we may miss our 4 month target

This is an okay place to start. It clearly raises the risk of missing the delivery date, but someone who reads this will have no idea how much they should worry about this. That doesn’t inspire a lot of confidence in our ability to deliver. We can make this better by adding probabilities.

We believe that the project will take 3-6 months. We're 30% confident we can deliver it in 4 months

This is getting better. We’ve now given people a percentage that this risk will materialize. If 30% probability of success is acceptable, people can move on with their day. If it’s unacceptable, they can dig in and start to help. This presentation still puts a lot of onus on the listener to deal with the situation though. We can take clearer ownership of the problem by saying:

We believe that the project will take 3 - 6 months. We're currently 30% confident that we can deliver it in 4 months. Can we brainstorm areas ways we can increase this confidence?

Ending with a question makes a huge difference! We've turned a problem without an owner into one with a clearly defined owner (us) and a clear path for others to influence it via a brainstorming session. This may be the best we can do if we don't control the project plan. If we control the project planning, we can show even stronger ownership.

We believe that the project will take 3 - 6 months. We're currently 30% confident that we can deliver in 4 months. Much of the risk is in implementing the new UI components, so we'll mitigate that with a spike next week. In the meantime, can we brainstorm areas where we can possibly cut scope or otherwise increase confidence?

This approach gives us everything that the previous answer does, but it also shows that we're aware of the risks and are decreasing their likelihood of materialization. This builds confidence in our ability to manage the project to a satisfactory conclusion.

This example makes it seem easy, but the truth is managing other people’s confidence levels is hard. In the swirling world of project leadership you've got many things to juggle, and sometimes perfect communication gets dropped in the process. Fortunately, you can consistently create confidence and avoid alarm by making sure that you describe risks with a probability and either an action or a request for support.

Big thanks to Bill Hewitt, who made this post infinitely better with his feedback.

Book Report on Software Estimation - Demystifying the Dark Arts

2020-04-06T00:00:00+00:00

Estimation is something that I've done for a long time, but I've never really felt like I've done it well. I started rectifying that by reading Steve McConnell's Software Estimation: Demystifying the Black Art. The book is chock full of great ideas, and I've summarized them here for anyone looking to quickly improve their estimation skills.

Estimates vs. Targets vs. Commitments

The book starts off by talking about three things that often get confused:

Commitments are dates that you have told external stakeholders that something will be ready. This is commonly a public launch.
Targets are goals that you're trying to hit. They could be a feature that you're trying to launch by the end of the month, or it could be a metric that you're trying to move by some amount by the end of the quarter.
Estimates are analytical statements about how long a team thinks it will take to deliver a set of functionality. These should be decoupled from commitments or targets.

We often confuse these things, and it results in missed opportunities for collaboration. Consider the case where a PM wants to give a live demo of a new feature at a conference next month. Engineering estimates the feature, and finds that it will take two months to deliver.

At this point, we should realize that we have two things: a target to deliver by the conference, and an estimate about how long the scoped work will take. The estimate suggests that the target will be difficult, so the team can take a few actions. The team can set a similar target with guardrails, they set a less ambitious target, or they could even keep the same target, but accept the risk that they may fail and have no demo. The one thing they shouldn't do is quibble over the underlying estimate unless there is a problem with the analysis.

Count, Compute, Judge

Once that difference is established, the book moves on to discuss how to produce accurate estimates. McConnell a three step process called count, compute, judge to do this.

The first step in count, compute, judge is to get an unbiased estimate of the size of your software by counting things related to its size. The things that you count will be dependent on your application, for UI applications it may be new screens, but backend applications may count new ETL jobs and new API endpoints, but it's important that you count something to get an unbiased read on the size of your project.

Once you've counted, the next step is to compute an estimate. For example, let's assume you're estimating a new feature. First you look at the mocks and you see that it will require 6 new screens, 3 new API endpoints, and updates to 2 API endpoints. You then look at historical data and see that it takes your team an average of 3 weeks to build a new UI screen, 2 weeks to create a new API endpoint, and 1 week to update an existing endpoint. This would mean that you estimate

 6 * 3 + 3 * 2 + 2 * 1 = 25 total staff weeks.

This estimate is delightfully free of bias, but it can't account for the fact that each feature is unique. That's where the last step, judge, comes into play. You use judgement to tweak your initial counting and computations. In our case, you may notice the that API endpoints are in hairy parts of your code, so they will take longer than average. This may mean that we bump up our estimate of staff-weeks per API update to 2.5, giving us a new estimate of

 6 * 3 + 3 * 2 + 2 * 2 = 27 total staff weeks.

This estimate is still grounded in data, but now it's informed by judgement.

Estimating in Ranges

It can be easy to see this single value as The Estimate, but that would be flawed. Sometimes stuff goes way faster than we expect, more often it takes longer. Your estimates need to account for this variability by incorporating ranges.

The simplest way to do this is create a best case, a worst case, and expected case estimate complete with the underlying assumptions that created the estimate. Combining estimates and assumptions will give more accurate estimate and more tools to ensure a successful project.

Compare these two estimates

"The project will take 27 staff weeks"

vs.

"The project will take between 15 and 48 staff weeks, with an expected effort of 27 staff weeks. If we can find a lot of code re-use and the project gets fully-staffed we can save 2 and 3 weeks respectively. If the design mocks turn out to be really novel it could cost us up to 6 additional staff weeks."

The second estimate is more useful: it allows us to make informed engineering staffing decisions and shows us where we should can best focus our effort to derisk the project.

It's also worth noting that outcomes on projects aren't normally distributed, so they don't need to be symmetric around the expected value. In our example above, our best case was 12 staff-weeks lower than the expected case, but the worst case was 21 staff-weeks higher. That's okay. What matters is that you used the correct inputs into the estimation process.

The Cone of Uncertainty

Estimating in ranges is tightly tied to another key idea in the book: The Cone of Uncertainty.

The cone is a visual representation of the fact that at the beginning of a project you have very little information, so you're very uncertain about how long it will take. As the project progresses you gain information and increased certainty until it is finally delivered. This has a couple of implications for estimates.

First, it means that at the beginning of a project you can probably only count very coarse grained things, so your best + worst cases may be quite different. These estimates will progressively narrow as you move down the cone.

This increasing clarity also means you'll want to use different estimation strategies depending on where you are in the project. In the beginning of the project you can really only count proxies for project size, so a quick and rough estimation technique like t-shirt sizing will do. As you get further on you can start to estimate individual tasks with more accurate estimates.

Communicating Accuracy in Estimates

The last point that comes up frequently is how to communicate the accuracy of estimates. Frequently your process of counting + computating will give numbers that seem very accurate but your estimation method couldn't have given you that degree of accuracy. For example, let's say that you're early in a project, you count the find that you have 23 components left to build and expect each one to take 7.25 staff days. That gives you 166.75 staff days of work.

That number seems very accurate, but much of the accuracy is a mirage. There is no way you can tell down to the quarter-of-a-day how long a 7+ month long project will take. If you present this estimate in its current form, they'll say "gee, it sounds like Maltz has really done his homework. He's working with 2 other engineers, so I should expect that in exactly 8 weeks."

This is not good. Slipping by 4-5 days on that estimate will seem like a miss, even though that's totally reasonable when you're at this stage. There are two easy techniques to avoid this.

Remove significant digits. 166.75 Staff days reads different than 167 staff days, which is different still from 175 or 200 staff days. These differences in reported accuracy will help others calibrate their expectations.
Change the units you estimate in. If you estimate down to the day, people will assume you're controlling the project down to the day. If your units are weeks, or months, people will assume less tight control. In our example above, changing 166.75 staff days may be better estimated as 33 staff-weeks or 7 staff months.

These ideas are the most common threads that run through Software Estimation: Demystifying the Dark Art, but there are many more. I found it to be brimming with strategies and tactics that immediately helped me become a better estimator. If you're trying to level up your own estimation skills I'd highly recommend picking it up.

A big thanks to Michael Stephens for reading an early draft of this post.

A Default Approach to Quarterly Planning

2020-04-05T00:00:00+00:00

Teams often find themselves in a position where they need to figure out how much work they can commit to, most commonly in quarterly planning. If you've never done this before then wading through a world of possibilities to get to a commitment can feel impossible. Fortunately, I've found that a default approach can help you establish a plan reasonably quickly and with minimal overhead.

Before going further, I've created this this spreadsheet. as an example of this process for a theoretical food delivery company. We'll be revisiting the spreadsheet a couple of times, so take a quick skim of the first row of each sheet.

Skimming successful? Great. Let's move into the details.

Step 1: Figure out your goals

Before you go figuring out what to build this quarter, you need to figure out what you're trying to achieve. In Silicon Valley, this frequently looks like defining OKRs, but any goal setting framework will do. What's important is that you have some common yardstick to measure each project's impact and prevent the loudest opinion from dictating what the team will work on.

After you've defined your OKRs, write them down so they can be referenced later in planning. This should give you something like the first sheet of our example.

Step 2: Make a list of projects and their impact

Once you have your goals, the next step is to write down possible projects and their impact. In the interest of keeping this list manageable, a "project" is something that will take more than 1 staff-week of work. Many of these will be user-facing features, but you also want to collect engineering-focused projects here.

Each of these projects should include a short description of the requirements and a description of its impact. As much as possible, engineering and product-focused projects should describe impact should be in the language of the goals defined in step 1. This will help make sure that all projects are prioritized on equal terms.

Step 3: Put estimates on all projects

Once you have a list of projects and their impact, the next step is to put estimates on them. There are a variety of ways you can do this but, I've found that having the people close to the work give t-shirt sized estimates is a good approach here. T-shirt sizes are nice for this because they give high and low estimates, which appropriately convey uncertainty, and they can be assigned quickly.

At this stage, you'll also want to allow for a little bit of push-and-pull on requirements. If there are ways to deliver a subset of the project at a fraction of the cost, you'll want to surface that now so that you can incorporate that information in later stages of planning. However, you don't want to negotiate over specific requirements at this stage, as that can quickly become a time-sink.

Once you've done this, you should have a spreadsheet that looks something like the second sheet in our example.

Step 4: Figure out your capacity

Now you've got projects, impact, and estimates. The last input we need for a plan is an understanding how much the team can accomplish. Having historical velocity to calibrate against is best, but in the absence of that you can get by with taking the number of staff-weeks available on your team and applying a consistent haircut for things like PTO, on-call, and high-priority small tasks.

If you want to more accurately assess team capacity, Steve McConnell's Software Estimation: Demystifying the Black Art has a number of good techniques.

Step 5: Establish your overall plan

Now we have all the inputs into our plan, the last step is to actually make it. The simplest way to do this is to start filling up your team's queue with the "best" projects (probably defined as highest impact-effort ratio) until the sum of their high estimates is equal to team capacity. These are your "green" projects: the ones you'll plan around for the quarter.

Then, keep stack-ranking the remaining projects until the sum of their low-estimates equals the team's capacity. These are your "yellow" projects; the ones you'll work on if things go well, but will get cut depending on how the quarter goes.

Finally, you'll have a bunch of projects that don't make the cut. These are "red" projects, and they just won't happen this quarter unless something changes.

After this step, you should have something that looks like the third sheet in our example.

Step 6: Sanity check with a Gannt Chart

Once we have a plan, I like to check the results by making a quick gannt chart. The purpose of this is sanity check your assumptions and look for anything you'll need to plan around, not to make a strict schedule you'll follow for the quarter. It will probably accurately reflect your team's work over the next ~4-6 weeks, but will become more speculative after that.

After adjusting your gannt chart for things like deadlines and staffing requirements, you'll end up with something like the final sheet in our example spreadsheet. Congratulations, you've got a quarterly plan!

Step 7: Share a narrative of your plan

Now that you've got a plan, chances are other people in your company will care about it. You could share the spreadsheet you used to make the plan, but that's not easily digestible. Instead, you'll probably want to turn your plan into a narrative document. There are lots of ways to do this, but I like to follow Guarav Oberoi's Medium post on building product roadmaps as a default approach. His process for getting to a roadmap is slightly different, but the end product can be identical.

Sharing this out in a narrative format can also help other teams understand what you're accomplishing and allow them to easily give feedback if you're missing any assumptions.

What are the strengths and weaknesses of this approach?

Overall I've found this approach to be effective for understanding what a team of ~4-8 people can build over a ~3 month time horizon, which makes it perfect for quarterly planning for a feature team where you don't need crystal-clear accuracy over for the quarter.

At the same time, this approach isn't a panacea. In particular, it has a few limitations:

It hand-waves over external dependencies. This means that if you're in an environment where you have a lot of dependencies, you may want a broader process similar to this "W-shaped" approach. If nothing else, it makes sense to follow Guarav's advice of making sure to call out dependencies as a risk in your narrative.
It doesn't give super accurate estimates or clear project plans, especially if you estimate with t-shirt sizes. I've found this to be mostly fine since our main goal with this process is to establish "what work can we plausibly do", not a perfect schedule. Once we've established the work we can take on, then we can start to manage individual projects and create a more accurate schedule.
It starts to break down past ~3 months. The lack of dependency tracking and rough estimation approaches means this is fine for ~1 quarter, but not much further than that. If you need planning past the quarter-level, consider other approaches.

In spite of these limitations, I've found that running this process is a great way to cut through ambiguity and get a quarterly plan pretty quickly. It's my default tool when I need to run a planning process, and would recommend it to others who are just getting started with quarterly planning.

This post was made way better thanks to feedback from Antonio Verardi and Joe Orsini.

Evolving Communication Structures With Exponential Scheduling

2020-03-28T00:00:00+00:00

One of my challenges at Nuna has been setting up team-level communications structures in the face of uncertainty. Going from 0 to 1 means that our understanding of the problem constantly evolves, and with that, our communications structures need to evolve with it. I've managed to grapple with that change through an approach I call exponential scheduling.

Exponential Scheduling

The basic idea of exponential scheduling is simple: whenever we see an opportunity to refactor our communications structure we try a small change, and then repeat that an exponential number of times until we've reached a happy medium.

In practice this means that when we see a communications gap we don't start by putting a hour-long meeting permanently on people's calendar. Instead, we talk for a few minutes, and form a hypothesis about how to fill that gap. Sometimes this means starting a weekly meeting, but other times it has meant sending out a semi-regular newsletter. For the purposes of this article, I'll assume it means setting up a weekly meeting.

Once we have our hypothesis, we try it for 1-2 weeks, and we ask ourselves "was that useful"? If so, we extend it out to 4 weeks and revisit. After that, we do it again, this time for 8 weeks. Finally, after 8 weeks, we make it a recurring part of our schedule.

We can do the same thing in reverse. If we notice a regular meeting has been thin on content, we won't pull it off the calendar, we'll halve the frequency, make a note to revisit in a month, and let that run for a couple iterations. If it's still thin on content, we'll re-evaluate and remove the meeting altogether.

Why I Like This

The biggest reason that I like this is it makes it easy to try out new communication structures. Adding recurring meetings is often met with "ugh, another meeting", and removing them can be met with FUD about the impact on team cohesion. With exponential scheduling, we can mitigate both of those by defining a small, reversible experiment with a clear re-evaluation path in case we're wrong. This helps us capture the upside of making the change, while mitigating downside-risk if we're wrong.

The other advantage with this approach is that it helps prevent calendar overload. In order for a meeting to stay on the calendar as a recurring event, it needs to prove its value 3 times over the course of a quarter. This helps prevent calendar inertia from accidentally filling up peoples' time.

When is this the wrong choice?

As with all tools, this one doesn't solve everything. In particular, this approach doesn't work so well if you are undergoing a re-org and the fundamental structure of your team is changing. In those cases, it's probably worth setting up a default comms structure and then evolving.

Another time when this approach struggles is if the experiment means trying out a new structure or learning new skills. In these cases, the first couple of tries may feel a little bit chunky as you work out the kinks. If you anticipate that happening you can still use this approach, but make your initial experiment longer and set expectations accordingly so that people don't give up after the first iteration.

I'd also speculate that this is the wrong choice is if you're in a position where there are multiple, interlocking communications problems and the incentives are not obviously aligned around fixing them piecemeal. In those cases, I'd speculate that the move is to find a decision maker and work with them to fix the underlying problem. However, that feels like an extreme move, and one that I've never had to use.

Overall, I've found that much like incrementally refactoring your code with small changes, incrementally refactoring communications structures with small experiments has been very useful. It has allowed us to set up resilient structures and has prevented us from accidentally locking in long, useless meetings.

How do I get my ideas prioritized?

2019-11-27T00:00:00+00:00

A while ago I was struggling with the question of "how do I get a project prioritized." I had an idea that everyone agreed was good, but it was languishing and other work was getting prioritzed. I talked to a mentor and he gave me a three-step process that I've since found very useful. The process goes something like this

Step 1: Identify the decision maker

Who is the person who can grant you the authority to do the thing you want to do? Chances are this is a product manager, or someone above you in the management chain. If you can't get a clear answer here that's part of the problem, and you should work with possible decision makers to get one (or a group) appointed. If you can't reach a consensus on a decision maker, escalate and get someone to appoint a decison maker.

Step 2: Figure out what the decision maker cares about

You may think you have the most whizz-bang idea under the sun, but if your decision maker doesn't see why it matters to them you won't get very far. Spend time to figure out what matters to your decision maker. You can get a first-pass idea of this by looking at what metrics they track (probably in the form of OKRs), and then you can sit down to talk with voices for a more qualitative understanding.

Step 3: Figure out what will not happen if your decision gets made

Time isn't infinite, so if a team starts to do your thing, they won't be doing something else. Figure out roughly how large your idea is, and what would get cut if your team undertakes it. This is a great time to brainstorm ways to figure out to trim your idea down to its simplest form, or figure out how you can align what you want to accomplish with an existing endeavor. Both of these minimize how much work needs to be cut, and will likely make your pitch easier

After you do this, evaluate whether or not your idea will help the decision maker in the axes that they care about. If not, you should probably reconsider your idea, or try to reshape what matters to your decision maker (probably by changing the larger group's metrics)

Step 4: Make your case in the language of your decision maker

Present your idea to your decision maker, along with what will be cut, in a succinct format. The format will depend on your context, but the core structure of your message, but it will probably look something like: We are currently doing X. If we start doing Y, then it will help us achieve goals 1 and 2 faster/better/more reliably; this will mean we will need to change Z, but we can safely do that by undertaking these mitigations. I propose we start doing this by taking a step move this forward. Should we take that step?

This probably won't get you an immediate "yes", but you should leave this presentation with a clear action item of how to move forward on your idea, even if that answer is "not now, let's evaluate after 2 months."

An Example: Building Container Infrastructure

A while ago I thought that we should start to invest in building our container infrastructure for our web platform. This would require us to get staffing from our infrastructure team to build something that was reusable across all of our systems. I identified the decision makers as the team lead for our infrastructure team and the manager for our web team.

Next, I figured out what each of them cared about. Our web manager had an OKR around launching our batch API and decreasing the time to create new integrations, and the infrastructure team lead had an OKR around enabling developers to fast feedback on infrastructure changes.

I looked at what we were doing currently. As part of our current integration, we were spending some time doing manual infrastructure configuration. I knew that with Docker we could turn these into ephemeral environments. That would be some upfront costs, but it would make future client integrations faster. It would also mean we could test our infrastructure changes locally by building containers. This aligned with both the web team's KRs, and the infra team's KRs.

Now we had our first three things: we had identified decision makers (web manager + infra team lead), figured out what mattered to them, and figured out the tradeoffs involved in building our idea (slower delivery of current feature, and later delivery of some other features), but still felt that the trade-offs were worth it given our KRs. There was a risk that our containers work would take longer than anticipated, but we'd built a prototype to mitigate some of that, and we always had our quick and dirty original approach if we needed it. Lastly, we had to make the decision.

To do this, I had a meeting with all the stakeholders and wrote a 2-pager detailing the above, and asking for a clear decision: "should we spend 1 month of 2 engineers' time to build this feature using containers?" There was a little bit of back and forth, but eventually we decided "yes, this is what we should do" and we built the thing.

All of the above sounds easy, but it took around 6 weeks of discussions, drafting, prototyping, and refining before we ultimately took a call. Fortunately, by having a clear process, it never felt directionless. This has since been my go-to process for managing new ideas, and I'd recommend it if you're struggling to get your own ideas prioritized.

Is Conference Speaking Worthwhile?

2019-05-11T00:00:00+00:00

Over the past few months, a few people have asked me about my experience speaking and blogging, specifically through the lens of what type of opportunities it has opened up for me. My thoughts on this have been rattling around for a while, so I wanted to share them broadly in case other people have similar questions.

Some background

First, a bit of level-setting about exactly how much speaking/blogging I’ve done over the past couple of years. Since April 2017 I have:

Given tech talks at eight different professional conferences. These talks were generally well received and were well-reviewed. If you're curious about the topics, you can find all of them on my speakerdeck page
I’ve also published ~10 blog posts on technical-ish topics.
That content has gotten featured on a couple of Twitter lists and one of my decks was “Featured” on Speakerdeck for a day.

That works out to around 1 conference talk a quarter and one blog post a quarter. That roughly translates to "more content than your average bear, but certainly not a lot."

What has all this done for me?

First, let’s start by talking about the benefits.

Strangers on the internet have said I’m cool: Every once and a while I’ll get a tweet from someone saying they read my blog post or saw one of my talks and they enjoyed it. That’s awesome, and it makes me feel really good whenever it happens.
I’ve gotten to go to lots of conferences: This seems obvious, but it’s actually really important. My guess is most companies will fund you to go to one conference a year; I go to around four a year without paying for them. That means I get 4x the opportunities to immerse myself in content, grow as an engineer, and take stuff back to the my team. That’s been huge for me, and has definitely contributed to my breadth of technical skills.
My company has paid for me to fly lots of places: Work has covered every conference I’ve spoken at, even the international ones. This means that if I want to, I can extend my time in a new city for a couple days and pretty much only pay for the hotel. That’s pretty cool, and definitely something I appreciate.
I’ve gotten to meet a lot of cool people: By speaking at conferences I’ve gotten to talk with a lot of people I would’ve never otherwise interacted with. Most of the time these conversations are 30 minute hallway chats and I never see the person again (that’s okay!) but occasionally we’ll tweet at each other. Either way, conference speaking has brought me in touch with a lot of lovely, intelligent, and thoughtful people, and I’m grateful for all of them. As a bonus, many of these people were willing to talk candidly to me about opportunities when I was job hunting, and their referrals fast-tracked me into the interview process.
I've been forced to formalize my thoughts: Oftentimes my proposals are about non-technical topics, so once they get accepted I need to do a bunch of hard work to turn them into ideas which are digestible by others. This process of turning “weird amorphous brain soup” it into “coherent narrative” makes me better at that topic. I could probably do that via other means (reflection, journaling, etc), but speaking is the one I use.
I’ve gotten connected to some internet famous people: The “conference speaking circuit” (at least with in Android) is surprising small. Once I’d been to 3 or 4 conferences, I’d crossed paths with a lot of folks who were making cool Android stuff. None of them offered me a job immediately (although some did compliment my talks, which was nice of them!), but it definitely make it easier for me to ask them for thoughts/feedback on software topics.

What HASN’T this done for me?

Now that we’ve talked about what conference speaking has done for me, let’s talk about what it hasn’t done for me.

I haven’t made a bunch of friends I talk to regularly: Some people seem to have close friendships with their speaking friends, but I don’t talk to most of mine regularly. We mostly get together at conferences have dinner, talk about tech, and occasionally share thoughts on Twitter, but not much more than that (which is cool!). I’m super grateful what we DO we share, but it's definitely a different kind of relationship.
I haven’t gotten internet famous: I was expecting that after I gave my first couple of conference talks, I would have people lining up to hear what I had to say; that’s just not the case. I currently sit at ~550 Twitter followers, no one has ever reached out to me to speak on a podcast, and I’m certainly not a “thought leader”.
I haven’t gotten invited to speak anywhere (or even accepted more frequently): This sort of goes along with #2. I haven’t been invited to speak anywhere yet, and my proposals still only get accepted ~25-30% of the time. Maybe one day I’ll get invited to speak somewhere, but it’s not something I’m expecting in the near future.
I haven’t gotten any job offers from speaking: I sometimes see a meme of “Speaking got me my next gig” floating around as ‘why you should speak’. I don’t doubt that this has happened to other people, but it has never happened to me. Speaking has given me access to people who could refer me, but I still got rejected during the interview process. Maybe it takes more time for strangers to start giving you job offers from talks, but I don't know what the tipping point is.

So What?

So, where’s all that leave us? Good question! I don’t know! I think my takeaways after two years of conference speaking are roughly:

Public speaking is cool, and I’ll keep doing it: There’s a lot of upside to public speaking: you get to meet nice people and someone else pays for you to travel around and learn stuff. All of that is fun and if you’re into it, go do it!
Becoming internet famous is hard: I went into speaking expecting to give a couple of good conference talks and immediately have opportunities rolling in. That hasn’t happened, and I’m not sure how to make it happen. My guess is if you want to reap the rewards of internet fame, you need to tailor your content or just produce lots of solid content.
If you want to get started, work it into your day job if you can: Creating content is hard work; some people claim to be able to throw together slides the night before a conference, but it takes me at least 15-20 hours to create a polished talk. I manage this by setting aside ~1-3 hours a week to “create content for recruiting” which means writing conference proposals, slide decks, or blog posts. If you can swing that, I’d suggest trying it.
(Slightly more speculative) You get what you put in: I get the sense that many people who really trumpet the value of public speaking/blogging put a lot of their time and energy into it. If you really want to get those same benefits, my guess is you’ll have to invest similar amounts of time. I’m not sure what the cost/benefit curve looks like, but if you find out, please do let me know!

Roadmaps vs. Projects

2019-04-21T00:00:00+00:00

I had lunch with a friend yesterday, and he shared an interesting story. He was leading a large technical project at his company, and it started off fairly normally. They saw some fruit they thought would be low-hanging, ran the ROI numbers, wrote a project plan with clear milestones that showed value along the path, staffed the project, and started to deliver.

Over time, they started to discover that the low-hanging fruit wasn’t so low-hanging after all. They had to change some old systems in order to get at the low-hanging fruit, and the more they dug in, the more they realized that they didn’t understand the tech debt that stood between them and their end goal.

They reevaluated the ROI at each step of the way. On one hand, as they discovered this new tech debt, they were paying it down and making changes which would open up a whole class of errors. On the other, their project was slipping, management was getting antsy, they weren’t directly showing any ROI, and the problems seemed to involve progressively more teams.

Ultimately, my friend decided to cancel the remainder of the project. He also took all those technical hurdles which would enable large classes of work and turned them into a technical roadmap for the team, so that they could continue to unlock value in the future.

This highlighted an interesting set of trade-offs between roadmaps and projects.

Projects

The distinguishing factors of projects are that they are:

Clearly defined
Clearly staffed
Have a clear, specific goal with timelines
Are a relatively strong commitment

These characteristics make it very easy to rally a team around a project and get people to start delivering. The clear goals and staffing also makes projects easy to track. This is great if the team is delivering effectively, but can create pressure if the team struggles to meet its goals

Roadmaps

The distinguishing factors of roadmaps is that they are.

Aspirational
Interwoven within projects in order to achieve a larger goal
Less tied to timelines
Are a relatively weak commitment (i.e. they often change as circumstances indicate)

Both of these tools are valuable tools for a tech lead, but you’ll want to use them differently. If there’s a clear project with known scope and direct ROI, leaning on a project may be the right tool. If you have a series of efforts which provide value but culminate a far out, and possibly shifting, goal, a roadmap may be more valuable.

Writing Good System Overviews

2019-04-01T00:00:00+00:00

Over the years at Nuna, our data platforms have grown from small pipelines which served simple analytics, to large, polyglot pipelines which can help patients receive personalized doctor recommendations. As we’ve scaled, our inline documentation and README’s for specific libraries have been helpful, but haven’t been sufficient to help new hires understand how our whole system fits together. In order to help our “Newnas” get up to speed faster, we’ve written a different type of documentation: a system overview, detailing how the whole system comes together.

What’s a System Overview?

No matter how well you’ve architected your system, at the end of the day, it’s all just text. For someone to be productive in your system, they need a mental model of how the system works in order to translate the text they’re reading into higher level concepts. That’s where system overviews come in.

System overviews are documents designed to create a mental map of how a system works. When done well, they help provide the context new hires need to start delivering code quickly and with confidence. When neglected, or written poorly, system overviews can cause confusion for new members on the team as they work to understand the cause of an issue.

Building these mental maps may seem hard, but it only requires three key steps.

Step 1: Design a block diagram to provide a birds-eye view of the system

The first step in designing a mental map of the system is to create a visual model. Create a block diagram where the major components are blocks and the relationships between them are expressed as arrows. This diagram helps developers build a baseline understanding of the system and begins to demystify, and contextualize, the terms their teammates’ use when talking about their work.

It can be tempting to over-specify the details of this block diagram, but it’s best to strive for brevity and clarity rather than completeness. It’s more helpful to have a concise, rather than cluttered, diagram. You’ll be able to better express the additional details in the next component of the system overview.

Step 2: Write descriptions for each block

The block diagram introduces a rough mental model of how the system interacts, but doesn’t provide the supporting detail explaining how each piece operates. Understanding these details is essential to achieving a greater awareness of how the system functions.

This documentation doesn’t need to be an exhaustive description, but it should answer some key questions about each component. These include:

What is the purpose of this component?
What information does it take in?
How does it operate on the input?
What information does it produce?
Are there any special design considerations when making one of these?

The answers to these questions should be brief (2 paragraphs is a sweet spot) and allow people to look at any class and start to understand roughly what it does and how it fits into the system. Including these write-ups in your system overview helps others have a better idea of where their bugs may be hiding, or where to incorporate a new feature.

Step 3: Create a concrete example of the system in action

Close your system overview by creating a worked example to show step-by-step how the pieces in your system solve a problem. This last step helps to cement your readers’ understanding of the system, and turn theory into practice.

Good examples contain a few key traits:

They are real: Resist the temptation to create an example filled with names like
```
FooCleaner
```
or
```
BarProcessor
```
. Names like Foo and Bar are convenient, but they don’t help to build a plausible mental model. A contrived, but relatable, example is much better.
They include real, small code examples: Your system overview should contain code that demonstrates how to solve your example problem. This code should be long enough to help readers understand your descriptions, but shouldn’t go into too much detail.
They touch the whole system: If something appears in your block diagram, it should also appear in your example so your reader can develop a complete mental model.

Keeping system overviews up-to-date

Once you’ve completed these three steps — designing a block diagram, writing descriptions of each block, and creating a worked example — your system overview is in a good place. That’s not to say that our work is done; we still need to keep your system overview up-to-date as the system changes.

New users to your system are the best monitors of existing documentation, so have them review it as part of their ramp-up. After they’ve read it, have them explain what they learned and ask questions. Afterwards, revisit the system overview, and add any necessary detail to clarify any pieces that may be out of date.

Our system overviews are constantly evolving, but they’ve proven valuable in helping to establish a high-level perspective of how our systems work. While they require some time up-front to write, that investment has more than paid off in terms of easier onboarding as our systems become more complex. A system overview is never done, but we’ll keep evolving them as we update our systems and find new ways to improve patients’ quality of care.

Note: This initially appeared on the Nuna Blog I'm just cross-posting it here

Start Side-Hustling

2018-10-20T00:00:00+00:00

Back in university I worked in a media office, and it seemed like all the creatives had two jobs in their life: their real job, and the thing they did on the side. Our graphic designers would run a consultancy, our photographers would put together a magazine, and our videographers would were constantly shooting for events or contests.

I once asked the head of our office about this, and he sagely responded “everybody has to have a side hustle”. Although I didn’t understand it at the time, years later I’ve come to realize that he’s right: whether you’re a videographer or a software engineer, having a side-hustle at work can be a valuable way to grow your skills and impact.

Side hustling, what’s that?

A side hustle is pretty much anything you do which is not part of your specific job responsibilities. If you’re a software engineer, you could have a side hustle where you help define and maintain your team’s code review practices. Alternatively, you could spend time writing blog posts, or leading brainstorming sessions about team direction. You can even side-hustle outside of your day job (we call those hobbies), but for this purpose we’ll just focus on side hustles during your day job.

Now you may be thinking to yourself “Why bother with side hustles? Why not just keep doing and let someone else take care of that messy, non-coding, work?” The simple reason is because side hustles represent a huge opportunity for you and your team.

Side hustle opportunities exist because there’s a problem that needs to be solved and no ones currently solving it. Chances are there’s a problem brewing under the surface, but everyone else has been too busy to deal with it; this is good news for you! It means there's an opportunity for you to step up, fill that gap, and learn something new in the process.

Take the above example of a team that doesn’t have clear code review guidelines. On a team of three people, it’s probably not such a big deal: everyone has a social agreement about how code review should operate. However, as you onboard a couple of more engineers you notice that code reviews begin to slow down, and maybe start to focus more on nitpicking than important questions.

At this point, the problem is probably not the most urgent one for the team, so no manager or CEO is going to say “time to roll up my sleeves and fix this team’s code review disagreements”. However, the lack of code review standards is a very real problem, and one which left unchecked will lead to slow code reviews and a lot of grief for the team. If no one does anything and you onboard four more engineers, your code reviews may descend into slow, grinding, arguments. Fortunately, if someone steps up and solves the problem now, before it’s too late, the whole team will avoid this fate.

Side Hustles: Good For You Too

Side hustles don’t just help your team, they help you broaden your own impact. There’s always a limited number of technical problems to be solved, so you may not always be able to lead a shiny new engineering project. Side hustles allow you to find a new challenge even when the rest of your job isn’t pushing you to solve new challenges.

Once you start taking on side hustles you’ll also find that they bring you into contact with people you would have never otherwise met. These connections are rarely immediately valuable, but they can be immensely useful as you look for new opportunities, or even just a new way to solve problems in the future.

Okay, so how do I side hustle?

Great! You’re now on-board with the idea of a side-hustle and you’re keen to start your own, but you don’t know where to start. How can you get started side hustling?

Define The Problem You Want To Solve and Solve it Locally

First, you need to figure out what it is you want to solve and how to solve it. For me, this always starts with a problem that I’m experiencing for myself. Coming back to the example at hand I may say “I’ve been running into a lot of disagreements on code review lately. How can I fix that”.

With that problem in hand, I next try to figure out how to solve it locally. So, I may sit down and say “why do we do code review?” and “how can I make sure we avoid bikeshedding in code reviews?”. With those answers in hand, I’d try to build a set of personal code review guidelines and see how they work.

Look to see how the problem and solution generalize

Once you’ve gotten a local solution to the problem, the next step is to figure out how others view the same problem. The best way to make this happen is shockingly easy: talk to people and ask them how they feel about the same problem.

For me, this often consists of setting up coffee meetings three groups: peers with context on the problem, peers who are totally unfamiliar with the problem, and a brief discussion with The Decider(s), people who could block or empower any solution I come up with.¹

Generally these meetings consist of me saying “Hey, I’ve been thinking about , and I’m thinking we should do about it. What do you think about that?”. Generally I’m looking for a few things out of these conversations:

Is the problem a real problem, and is my solution on the right track? If I casually mention this problem to two or three people and no one says “yes, we should totally do that”. Chances are I’m looking at the problem the wrong way and need to go back to the drawing board.
Is there additional nuance on the problem? Frequently when I float ideas past people they’ll ask something I hadn’t considered. They’ll say something like “yes, I totally agree that we should have code review guidelines. How would we have those work across teams which have different codebases and release schedules?” I generally file these pieces of feedback away and see how I can incorporate them into the project.
Possible allies or co-side-hustlers Ideally, whenever I’m taking on a new side-hustle, I want to have once person working on it with me. This not only forces me to be accountable to someone, but also it provides a layer of redundancy and emotional support. Finding someone who is excited enough about your solution to join forces isn’t necessary, but it is helpful.

Define a project plan and an MVP

Once you've had your brief conversations and have gotten positive signals about your direction, the next step is to actually define what you’re going to do to scale up your idea. You wouldn’t launch a big feature without first writing up a design document; similarly, wouldn’t want to implement company-wide code review guidelines without having a plan for how to draft, review, pilot, and finalize them. So write down a plan for your project and make sure it includes a set of small milestones which allow you to start small, validate your idea, and then grow from there. Taking our example of code review guidelines, that plan would look something like this:

Draft key themes of code review and get them reviewed by senior engineers in 3 disparate areas
Take feedback create a first draft of code review guidelines, present to decider and previous engineers for feedback.
Create a second draft of guidelines, work through second draft until all parties are satisfied.
Create a final draft of guidelines, present it to other key technical stakeholders (maybe all principal engineers + managers-of-managers) and get approval
Circulate final draft to see if anyone has any blocking feedback
Share new guidelines with the org and put a plan in place to monitor their adoption.

Notice how this plan doesn't try to solve the whole problem at once. It breaks the problem down into discrete steps and then layers on complexity only once the foundations are solid. Whatever your goal is, you want to define a similar set of clear steps which provide lots of check-in points for others.

Plan in hand, it’s time to get empowered to start side-hustling. Generally doing this consists of a meeting with The Deciders, who you should have already identified and talked to. If not, here's a quick rule of thumb: if it’s a team-level change, that’s probably your manager; if it’s larger, it’s probably a manager-of-managers. Find your decider and tell them “So I’ve been thinking about and I think we should do about it. I’m thinking we can pilot this by doing and then . What do you think about that?”

For some people, this may seem weird. “I’m telling my boss what we should be doing? Don’t they know what’s going on?” Well, maybe, but it’s much more likely that they have 25 other things which demand there attention, so if you stroll into their office and say “hi, I’d like to solve one of those problems for you”, their first thought will not be “get out of my office plebe”, it will be “oh thank god someone is solving this problem for me.” Remember, the time between something becoming a problem and the time when it becomes a fire can be long, and filled with lots of pain.

Of course, they won’t always say “yes” immediately, but they may push you to revise/clarify a couple of plans. However, so long as you vet your idea up-front, chances are you should be able to move forward with your plan.

They said yes! Now what?

Great! You’ve gotten the okay for your plan. Now what?? How can you do your new project along with your “normal work”? The secret here is running your side-hustle just like another project.

Work in Small Chunks

You wouldn’t run a big engineering project by just trying to accomplish the whole thing all at once, and you don’t want to do that with your side hustle either. You should have defined an MVP, milestones, and a scaling plan as part of the proposal you showed to The Decider. Now’s the time to use that. If you haven't, then go make one.

Start by working on the first milestone on your project. In our case, this would mean just writing down some rough high-level principles and getting feedback on those. Execute on that piece effectively, document your learnings, and then come back to subsequent milestones based on what you’ve learned. Trying to do the whole thing at once is a recipe for getting overwhelmed, so keep your focus small.

Find the time

Once you have that plan, it’s time to start working towards your first milestone. Again, you should be treating this like just another engineering project. Start by breaking down your first milestone into a set of individual tasks, and begin working through them. You can even have bi-weekly planning meetings where you establish a goal for the week and then myopically execute on that.

I also like to block off 30-60 minute sections at the end of a day as “side-hustling time”. During this time I put down my normal work and only work on side-hustles. This calendar time is important for me, as it serves as a reminder to put down the urgent work I’ve been focused on, and refocus on making forward progress on this important task. It’s okay if I miss a couple of these, but I try to make sure to have at least one or two a week so that the project never slips into “neutral”.

You may also find that as you work through these milestones you’re stuck and don’t know where to go next. That’s when it’s a great time to shoot an email to The Decider and get some feedback from them. Chances are they can unblock you by pointing you towards a resource who can help you. Don’t expect The Decider to solve your problems, but they are useful if you’re at wit’s end and don’t know where to turn.

Get regular feedback

As you start to accomplish, you want to make sure to check back with the original person who you worked with to get sign-off. As you hit each milestone, report back to them with what you tried, what you learned, and where you are thinking of going next. They may not be able to jump in and directly lend a hand (remember, they’ve probably got other priorities), however, they will be able to serve as a good sounding board for possible landmines on your way forward.

You’ll often find that this project feels a bit slow and plodding. That’s okay! Your side-projects are never going to move as fast as the things you spend the other 36 hours a week working on. What’s important is that you keep moving forward and showing progress. If you do that, and you keep trucking through obstacles, you’ll find that over time your pilot becomes a full-blown solution. It won’t be fast, but you’ll find that the people you meet and the things you learn will make it worth the while.

¹The concept of deciders is universal, but I stole this particular version of the idea from Jake Knapp's excellent Sprint book.

A big thank you goes out to Michael Stephens, who reviewed early drafts of this post.

Do You Really Need That JSON Array?

2018-09-02T00:00:00+00:00

When building APIs, it’s common to run into a problem which is basically a form of “We want an API that will support a list of something.”. In situations like this, it can be tempting to just send back a JSON Array and call it a day. However, I've found that this is rarely the right decision, and by making a slight tweak to this design you can make your APIs much more extensible.

To understand why structuring your response as a top-level JSON Array may be a problem, consider the following: let’s say we’re trying to show a list of restaurants in an application. If we’ve naively serving up an array of restaurants from our API, that means our responses will look something like the following:

[
    {
         “restaurant_id”: 1234,
         “restaurant_name”: "My restaurant",
         “restaurant_cuisine”: "Indian",
         ... 
    }
    ... 
]

On the surface, this is totally fine: you can parse this JSON with any library and handle it easily. However, what happens if you want to do something like add a list of suggested search filters that the user could drill down by? With this API design you don’t have many options: you basically have to ship a breaking API change in order to support the new feature or create another endpoint.

The shame of the situation is that it’s easily avoided. If instead of sending back a top-level JSON Array, we made our top-level element a JSON Object with a single key, we would’ve ended up with a response which looked something like the following:

{
   “restaurants”: [
   {
       “restaurant_id”: 1234,
       “restaurant_name”: "My restaurant",
       “restaurant_cuisine”: "Indian",
       ... 
   }
   ... 
   ]
}

Now if we want to add search filters we can just add another key to the top-level JSON object, giving us something like:

{
   “restaurants”: [
       ... 
   ],
   “suggested_search_filters”: [
       ... 
   ]
}

Boom! Instant backwards compatibility with no hassle.

There are probably cases where adding the additional layer of nesting is not the right decision, but I’ve found that the flexibility provided by the approach outweighs the costs in all situations I’ve encountered. So the next time you’re thinking about building an API to surface a list of content and you’re tempted to reach for a JSON Array, ask yourself “should I make this an object instead”, it might just save you some headache down the road.

Practicing as a Software Engineer

2018-07-11T00:00:00+00:00

Continuing to grow as a software engineer can become increasingly hard as you become more experienced. When you first learn to code, there are an infinite number of new things to learn; every algorithm, framework, or concept is brand new, so there’s learning at every turn. Best of all, this happens organically. If you've never written code before, the mere act of typing into a computer and making it work is challenging and pushes you to grow. Over time though, that growth path starts to peter out: there are only so many language features you can learn or libraries to master before you start hitting diminishing returns. Past that point, the skills you need to learn become abstract questions like “how do I design better software” or “how do I lead a team”, and to grow those we need to think a little differently about how we build skills.

Why's it gotta be so hard?

One of the reasons it's easy to hit a plateau as a software engineer is much the educational material which exists is about accumulating knowledge. If you want to learn something, whether it's how to use MVP architecture, or how to leverage experience to become successful technical lead, you can probably find some content which will give you the knowledge. However, as Anders Erickson points out in his book Peak: Secrets From The New Science of Expertise, this accumulation of knowledge alone is not enough. Knowledge is great, but it's useless on its own; knowledge must be turned into skills for it to be valuable, and there's only one way to turn knowledge into skills: practice

Practice is something software engineers rarely talk about. We frequently say things like "surround yourself with the best people" or "stay up to date by going to conferences" and assume that people will take those opportunities and just figure out how to turn them into new skills. Sometimes this works well and you get motivated people who immerse themselves in knowledge and learn how to apply it to their own lives. However, this approach can also result in people being confused and frustrated if they hit a wall and are unsure needs to change in order to improve.

Ideally, we can break this cycle by using “deliberate practice”, which Peak describes as “the gold standard of practice”. In deliberate practice, students work with experts in their field to master specific exercises which push them to improve against clearly defined criteria. If you're training a skill with clear measures of excellence, like ballet or musical performance, this type of practice simply cannot be beat.

Unfortunately, we can’t apply deliberate practice in its strictest form to software engineering; we don’t have the same objective measures of “goodness” that ballet dancers do, so we can’t design specific training programs to reach those measures. However, that doesn’t mean we should throw practice out the window. We can take the lessons from deliberate practice and apply them to what Erickson calls purposeful practice. Purposeful practice doesn’t have the same objective measures of success as deliberate practice, but it does have a few key elements which make it far better than doing the same thing repeatedly and hoping for new results. In particular, purposeful practice uses focused exercises which push the practitioner outside their comfort zone. These exercises incorporate feedback so that the practitioner can see where they are improving. This means that we can apply purposeful practice to pretty much any skill by doing the following:

Decide on a thing you would like to learn
Figure out an excercise which will force you to do that thing better by pushing your boundaries in some way.
Get feedback on how you did on the exercise
Figure out how to do the exercise better next time

Applying This to Software Engineers

Now that we have this model of practice, but how can we apply it to improving as software engineers? The first step would be to identify the skills which make great software engineers. While a full list is outside the scope of this post, it's safe to say that all great software engineers can:

Write correct code with good velocity
Effectively communicate orally with peers
Design extensible and maintainable systems

Next we need to define exercises that incorporate feedback for how we’re doing. This is where things start to get tricky. How exactly can we tell if we’re writing “more correct code”? Do we shoot for 100% test coverage? Start using TDD and just assume that things are getting better? Measure the number of outages over the course of six months? None of these really feel like they can provide rapid feedback on whether we’re actually doing a better job at writing correct code. It's easy to see that and throw your hands up, saying "well, software is hard, we'll just do our best and keep muddling through", but there are some ways that we can push through that and design a purposeful practice regimen around these skills.

The first is what Peak calls a top gun approach to practicing, named after the famous flight school where students continually dogfight against top pilots. In the top gun approach, you don’t know the right way to practice ahead of time, so you just try to do the task you want to improve at. After you’re done, you go back and evaluate what worked and what didn’t.

Top gun pilots do this by reviewing videos of their dogfights, and software engineers can do the same with regular retrospectives where they discuss how to improve. These are most frequently applied to team processes, but it’s also possible to apply the same methodology to your own skills. For example, after shipping a large feature, you could ask “What parts of the system had few errors when we went live?” “What classes of errors did we encounter?” and “How will I prevent those errors next time?”. In this way, we can treat our past projects as exercises which help us improve in future projects.

What if we’re unhappy with this approach, and we want something more direction? Another option proposed by Erickson is that we watch expert performers perform a task and see how they accomplish the task. This helps us understand their mental representations so that we can emulate the same mental representations ourselves. With those representations in hand, we can design specific exercises which help build up each aspect of the desired mental representation.

For example, it may be hard for us to specifically train "how should we design better systems", but we may see that a great software engineer (perhaps one of our mentors) follows a three step process: they list list out all the major for the system, group the requirements them into a variety of different groupings, and list the tradeoffs between different groups. Once we understand this process, we can create exercises which help grow each of these skills and get feedback from the engineer on how well we did in each step.

What does it look like in practice?

So now we've talked about this idea of applying a practice-first mindset to growing our skills as a software engineer, but what does that look like in practice? Let’s take a couple of examples to see how we could apply our model of purposeful practice to improve in a variety of areas.

Technical Leadership

What's the class of skills to improve? Choosing the right solution for the current circumstances

What's a specific skill to improve? Generating Multiple approaches to solving a problem before settling on one.

What's an exercise? Before deciding on an implementation direction, write down all of the options along with their pros and cons.

What's the feedback mechanism? After generating a list of ideas, make a decision and show it to a senior member of the team (seeking feedback from an expert performer). Ask if they have any pros/cons that may have been missed, and which decision they would make. If different than the decision, discuss why they would make that and help get a clearer idea of what mental representations we should use in the future.

Becoming a Better Code Reviewer

What's the class of skills to improve? Code reviewing

What's a specific skill to improve? Taking time to evaluate the code review as a whole rather than just focusing on the individual pieces.

What's an exercise? Before clicking "submit" on a code review, take a moment to list alternative ways that we could approach this problem.

What's the feedback mechanism? Take a top gun approach and review the same code as someone else. See if you come up with similar to suggestions to them; if not, figure out how you can create similar suggestions to their sin the future

Becoming a better communicator

What's the class of skills to improve? Communication

What's a specific skill to improve? Succinctly communicate ideas to a variety of audiences.

What's an exercise? Mentally collect major bullet points before starting to talk.

What's the feedback mechanism? Take a top gun approach and ask a teammate for whether they thought you were too verbose or too brief in your statement. If so, try to and more or less content as appropriate in the future.

That just gives a few ways that we can apply this mindset of practice to growing skills as a software engineer. Almost all of them though follow a similar pattern: they’ve taken a complex skill and devised specific exercises to improve that skill, along with feedback mechanisms to see if we’re actually improving. After that, it’s a matter of doing the practice until you’re happy with the results. Of course, this doesn’t throw knowledge accumulation out the window. You still need knowledge to understand which skills to grow and how to build them. However, you want to be sure to combine any knowledge you gain with a practical practice path in order to really get the most out of what you learn.

Effective Feature Flagging on Mobile

2018-05-14T00:00:00+00:00

Feature flagging is a great way to reduce risk by allowing features to be turned off remotely, but only if it's done correctly. I recently incorrectly feature flagged some code at Yelp! and wanted to share some lessons learned to help avoid similar issues in the future.

First, Some Context

Our team is currently working on migrating our App's analytics system to use a new event logging library. Getting correct metrics is important, so we decided to start by dual logging all of our analytics through our legacy library and the new library and then comparing them for consistency. We had tested the new library, but we weren't totally sure how it would behave in production, so we decided to put it behind a feature flag in case anything blew up.

This process initially seemed super easy: as all we needed to do was add some code in our base Application class that looked like:

    LegacyAnalyticsSystem legacySystem = LegacyAnalyticsSystem();
    if (Features.new_logging_infra.isEnabled()) {
        // The legacy system publishes its analytics as a stream.  The new
        // subscribes to that and transforms them.
        newAnalyticsSystem.subscribeTo(legacySystem.analyticsStream()); 
    }

Before shipping we did all our normal dilligence. We wrote unit tests for the new system and tested cases where the flag was both on and off. Everything came up green, so we happily shipped to production with the flag turned on.

Once our release rolled out, our backend engineers started reporting issues where we were logging incorrect data from the new system. That wasn't great news, but fortunately, we had a feature flag we could use to run it off! We went into our feature flagging system, turned the feature off, and... the errors still persisted. This left us feeling a little like WTFMate?

After thinking about it a little more, we realized that we had incorrectly feature flagged this code. Our feature flag was only getting checked in our base Application class on app startup. This meant that the application would need to get killed and restart in order for our changes to take effect. Talk about bad!

What should we have done instead?

We had the right idea with feature flagging this code, but our error here was WHEN we actually checked the feature flag. Instead of feature flagging the point of subscription to the existing analytics system, we should have feature flagged the actual point of logging.

This would mean that our Application class had code that looked something like:

        legacySystem = LegacyAnalyticsSystem();
        newAnalyticsSystem.subscribeTo(legacySystem.analyticsStream())

Then, in our subscribeTo method, we should have included code which looked something like:

      fun subscribeTo(analyticStream: Observable):
        analytisStream.subscribe({
            if(Features.new_logging_infra.isEnabled()) {
                // Send the log event via the new infrastructure.
            }
        })

This would check whether the feature flag is enabled before sending any analytics, which would have meant that any changes on the backend were immediately seen on the client.

So what did we learn from all this?

This process left me with two big takeaways.

Feature flagging is great, especially for new infrastructure that you want to expose to production situations, but you're not entirely confident in.
Make that if you are feature flagging a piece of code, that the flag itself is checked frequently. A flag that is only checked once per application lifecycle is harder to turn off than one which is checked frequently.

Wan't to Make a Change? Stop Talking and Start Listening at Android Makers

2018-04-20T00:00:00+00:00

I recently had a chance to give a talk at Android Makers about how to work with cross-functional stakeholders to create change. While I'm not an expert on that by any means, it was a good learning experience for me to decompose my thoughts on how I work with others. The video is now live on Youtube.

Protecting Your Source Using Code Review To Improve Your Application Quality at Droidcon Boston

2018-03-27T00:00:00+00:00

I recently had the chance to speak at Droidcon Boston about one of my favorite topics: code review. A video of the talk is now on Youtube.

Finding Mentorship After Onboarding

2017-12-23T00:00:00+00:00

One of the first questions I got after giving my talk about mentoring new hires was (paraphrasing) "how do you deal with effectively mentoring people who are 1+ year into their time on the team?". This question has stuck with me over the past year, mostly because I didn't have a particularly coherent answer at the time, and I stumbled through answering it. Over the past year I've spent a lot of time thinking about my own process of acquiring mentorship, and I finally have a (more) cohesive answer to "how do you handle mentorship after onboarding". I wanted to take a chance to share those thoughts, in hopes that people who are 1+ year into their time on a team can chart their own path to getting the mentorship and resources they need to succeed

One of the challenging things about talking about post-onboarding mentorship is that it's very individualized, which makes in hard to systematize in the same way onboarding can be systematized. Everyone who is joining a new team has (broadly speaking) the same set of mentorship requirements. Regardless of their level of experience, they will need to get familiar with the codebase, understand the team's culture, and learn any essential processes that they’ll need to be following. This set of standardized requirements makes it pretty easy to define a team/company-wide ramp-up process that everyone can follow.

However, things get more tricky when it comes to mentoring after onboarding. After the newhire phase it’s dang near impossible to create a one size fits all approach for mentoring engineers. Everyone has such a wide variety of skills, working styles, and goals that it would be folly to establish a single specific process for everyone.

What this means in practice is that if you want to receive effective mentorship after onboarding, the process needs to start with you understanding what you want to learn. Do you want to level up your architecture game so that you can build more maintainable code, or do you want to learn how to understand your users better so that you can find the right features that match their needs? Both of these are valid options, but they require finding mentors with very different skills.

It's worth noting here that figuring out an answer to “what skills do I want to learn?” is incredibly abstract and can lead to overwhelming decision paralysis. One way I overcame this was to decompose this question into three simpler ones:

Who do I look up to?
Why do I look up to them?
What do I want to be working on ~5 years from now?

After running through this exercise I discovered two things. First, everyone I looked up to was both a strong technical contributor and an empathetic communicator. Second, I want to work on data-focused products in the future. This led me to seek out mentors and opportunities which taught me to be a stronger communicator who can build data products. The specific skills that you admire may be totally different, but what's important is that you find clusters of skills that matter to you; these are the skills that you'll want to focus on getting mentored.

You may find this exercise gives you a large number of mentorable skills, but I always try to pare it down to one or two key areas to focus on at a time. It can be tempting to attempt to get better at everything all at once, but this eventually becomes a fool's errand. At a certain point, it becomes important to invest in nuance over novelty and buckle down on improving one or two skills before you focus on leveling up other ones. One other important thing to keep in mind as you're deciding on what to learn next is you can both learn from a prospective mentor and apply in practice. You may want to learn everything about machine learning, but if you don’t have any opportunities to actually apply any ML concepts, then it may not be right to find an ML engineer as a mentor because you won't be able to practice what you learned.

Once you've whittled to one or two skills, you may think "zomg, there's no way I can find someone to teach me these two very different things." That's okay! There probably isn't one person who can help you learn all the skills you're looking to grow. Every mentor will come with their own skills and experience, none of which will perfectly match what you need. Instead, once you have your list of skills of you should strive to form a career board of directors, each of whom teaches you a unique skill, rather than a single mentor who can teach you everything. Fortunately, if you've followed identified people you admire, you've already got a head start on finding who you want to sit on this board

Once you've identified potential candidates for your personal board, it's time to reach out and see if any of them is willing to be a resource for you. Surprisingly, I've seen many people get stuck after they find a prospective mentor and ask “how do I get them to mentor me?”. The answer is simple: you just ask them to help you with something specific! SO MANY people (myself included) find someone awesome that they wish could learn from, only to have self-doubt creep in and say “oh, that person’s too busy/important to get coffee with me” or “I should figure this out on my own and not bother them”. In these cases, self-doubt needs to slow its roll for a few reasons:

The worst thing that happens is they don’t respond or say “sorry, I’m too busy”: No one is going to laugh you off an email chain for asking for help, and if they do, congratulations, you have just found a jerk who you decidedly did NOT want to teach you. Most people genuinely do want to help, so the worst response you’ll likely get is “sorry, I’m too busy” and life goes on.
Mentoring is incredibly high-leverage for the mentor: A good mentor can spend 30-60 minutes with you a month and make you tremendously more effective. If you work at the same company as your mentor, this means them mentoring you is a net win for THEIR CAREER.
Mentoring feels good: Everyone likes feeling listened to, and mentoring is an opportunity to have someone listen to your perspective for an extended period of time. That makes mentoring enjoyable for your mentor as well as yourself.

Once you’ve kicked self-doubt to the curb, you can email your potential mentor to ask to talk with them about whatever you’re interested in. If you’re unsure what to say, try this handy email template I use to get coffee with literally anyone:

Hello <person>! My name is Jon Maltz and I’m a <thing you would be able to relate to>. I saw your <thing that makes me think you’re awesome> and would love to talk more about <concept>. Do you have time to get coffee over the next couple weeks to talk about that?

Again, the worst response you get here is “sorry, I’m too busy”, but chances are they’ll say “I’d be happy to”, and you can go meet with them. When you do this, make sure to come prepared with specific questions that they will have a unique perspective on. Your mentor's time is valuable, and you want to show that you value it by asking them questions that you can't answer with a Google search.

This first interaction may surprise you: you may come prepared expecting to have answers handed to you on a silver platter only to find that your prospective mentor isn't helpful in the way you expected. That's okay! There's no harm in thanking them for their time and going on your way to find someone who does fit with what you're looking for. When I'm looking for a new mentor, I like to run "mentoring adoption tests", where I get coffee with a couple of different people to see which one I communicate best with. Once I find someone I click with, I'll send a follow-up email that looks something like this.

Hello <person>! Thanks for taking the time to discuss <interesting thing> with me. I’m working on improving <growth area> and really appreciated your perspectives on <concept you discussed>. Is it cool if I schedule time every <cadence> to get your perspectives on the challenges I encounter as I try to <do thing which will allow me to apply the things you're teaching me about>?

Bear in mind that you will probably want to meet people at different frequencies depending on their availability and what you're trying to learn. Some people may be really helpful at figuring out the tactical day-to-days of your problems and are worth meeting frequently', while others provide more high-level perspective and don't provide as much regular value. My own collection of mentors at Yelp contains 3 people, all whom I meet at different intervals.

Scott Triglia: Tech Lead. I now get coffee with Scott once a month in sessions that I jokingly refer to as "Scott and Maltz contemplate the universe", where I ask a high-level question like "how do you think about working in a technology where you're not an expert?" and we talk about them for 30 minutes. These don't provide anything specific for me to do THAT DAY, but they do provide me a framework for thinking about tackling larger-scale problems.

Justin Cunningham: Technical Lead. Justin is the overall lead for our data efforts at Yelp, so has more context on my day-to-day than Scott does. We have weekly 1:1s where we discuss how to move forward with my piece of a larger project. These give me tremendous insight into the specifics of delivering a large project, keep my piece of the project aligned with the overall vision, and teach me lots about delivering a large, multi-team software project.

Brad Barry: Eng. Manager. Brad and I get together every 2-4 weeks to talk about what we've got going on in our life/work. Brad's been out of the code-writing game for about a year now, so I rarely ask him about anything technical. At the same time, he is tremendous at thinking about how to teach and grow others, so I will usually pitch him my latest blog post or conference talk to get his thoughts on how others might receive that message. This outside perspective helps me get a broader perspective about how to create content that's useful for other engineers.

I hope that gives you a sense for the variety of different mentoring relationships that I've built up, and how I’ve structured each relationship differently depending on what I want to learn. All of these relationships evolved organically as my own needs + questions evolved, but they all started out the same way: I found an area where I wanted to grow, I identified someone who could help me improve in that area, and I scheduled time to regularly bring them clear questions that were on my mind.

Happy learning!

Adventures in Gradle Dependency Resolution

2017-12-11T00:00:00+00:00

Currently at Yelp I'm working on building out our next generation experimentation infrastructure, a large part of which involves writing a Java wrapping library around a Rust library which does most of the heavy lifting of our experimentation. Yelp is mostly a Python shop, but we also have a few backend Java services; this meant that when we went to implement our Java wrapper, we decided to just write it once in pure Java and write a thin layer of Android code on top of that to provide Android-specific capabilities like logging to adb.

This means we have a single Gradle project which is built something like this:

Since our Java code communicates with our Rust code over FFI, we can't just pass configuration objects into our Rust library to control its initialization Instead, we need to pass the desired configuration to the Rust library as a JSON string, and then let Rust create the necassary models on its side of the FFI boundary. Unlike Android, which provides the org.json APIs by default, Java does not come with JSON capabilities built-in, so we needed a library which could create JSON strings for us. We took a quick look at GSON and Moshi, but were both way heavier than we needed for our purpose. Instead, we decided to use Google’s json-simple library, which exposes a very similar API to the one that Android exposes.

From there, library development went swimmingly until we went to add the latest version of our Android library to the Yelp app. When we did that, our app would fail to build with the following error:

  Warning: Conflict with dependency junit:junit. Resolved versions for 
  app (4.10) and test app (4.12) differ

What the heck is going on here? Digging around in the Android documentation, we discovered that Android creates an instrumented version of your app for testing, and will yell at you if there are any difference between the instrumented version of your app and the normal production one. This is super helpful, as it prevents you from say, using OkHttp 3.5 in your app and relying on some behavior there, but testing against OkHttp 3.3, where that behavior doesn't exist.

We started bug hunting by first looking in both our library code and app code to see where JUnit 4.10 was coming from. However, we quickly found that we declared JUnit 4.12 for all of our compile configurations in both our Java wrapper and our Android application. What's more, we reasoned that Gradle's default dependency resolution strategy should always choose JUnit 4.12 even if we did let 4.10 slip in as a dependency.

After scratching our head for a while, someone on our team had the idea to look at the pom.xml for json-simple (Gradle uses Maven's pom.xml format for resolving dependencies, even though it is a separate build system) and discovered that JUnit is declared as a dependency of json-simple. This meant that when we pulled in json-simple as a implementation dependency, we were also packaging all of JUnit 4.10 with our app! Then, when Gradle went to build our app, it was finding a conflict between the version of JUnit we accidentally dragged in and the version we cared about for our tests.

The solution to this was to include a little snippet in our app’s build.gradle file.

    allprojects {
        configurations.all {
            resolutionStrategy {
                eachDependency { DependencyResolveDetails details ->
                    switch(details.requested.group) {
                        case 'junit':
                            details.useVersion junitLibVersion
                            break
                    }
                }
            }
        }

This snippet basically tells Gradle “anytime someone specifies a JUnit dependency, ignore the version that they set and use junitLibVersion (in our case 4.12)”. For more about ResolutionStrategies, you can check the Gradle docs.

After we added this snippet, we could build and test the app. Huzzah! However, we hadn't solved the root cause of our problem (JUnit being packaged with our production app), so another snag came up when we went to merge to master and create a release build. All of our tests passed, but the our release apk build step failed with the following errors:

    Warning: there were 5 instances of library classes depending on program classes.
    You must avoid such dependencies, since the program classes will be processed,
    while the library classes will remain unchanged.
    (http://proguard.sourceforge.net/manual/troubleshooting.html#dependency)

When we went to the link, we saw the following description of this error:

In Android development, sloppy libraries may contain duplicates of classes that are already present in the Android run-time (notably org.w3c.dom, org.xml.sax, org.xmlpull.v1, org.apache.commons.logging.Log, org.apache.http, and org.json). You must remove these classes from your libraries, since they are possibly inconsistent, and the run-time libraries would get precedence anyway.

"Libraries that use org.json" sounded a lot like us at first glance, especially since json-simple's package is awfully similar to org.json. However, json-simple has its JSONObject class packaged as org.json.simple.JSONObject whereas Android packages this as org.json.JSONObject. Java uses fully qualified names in order to resolve classes, so we determined that this warning was not due to duplicate JSON packages. After a bit more head scratching, we then went back to the initial console output and saw the following:

    11:27:32 Warning: library class android.test.AndroidTestRunner extends 
                      or implements program class junit.runner.BaseTestRunner
    11:27:32 Warning: library class android.test.InstrumentationTestCase extends 
                      or implements program class junit.framework.TestCase
    11:27:32 Warning: library class android.test.InstrumentationTestSuite extends 
                      or implements program class junit.framework.TestSuite
    11:27:32 Warning: library class android.test.suitebuilder.TestSuiteBuilder$FailedToCreateTests 
                      extends or implements program class junit.framework.TestCase

It turns out that our JSONObjects were not the problem at all, it was JUnit! It turns out that forcing JUnit 4.12 resolved our dependency mismatch between test and real apps, but we were still packaging JUnit with our actual application! This version of JUnit was providing classes that Android already had a copy of, and Proguard was helpfully making sure that we didn't get nondeterministic behavior.

Once we figured this out, the fix was straightforward. We didn’t actually need JUnit at runtime, and we’re already compiling it in for our tests. So we can just exclude all of our JUnit dependencies when we depend on the Bunsen library. This is easily done with Gradle by including:

    implementation("com.yelp.library:$libVersion", {
            exclude group: 'junit'
        })

After that, everything worked beautifully and we merged to master smoothly.

Looking back on this process, a few things stand out as learning experiences for me:

Take time to read your error messages: It’s so easy to read one line and think you know what’s going on, like when we saw “oh, an issue with org.json”. Before implementing, take the time to read glean as much information as you can from your logs. It’ll make your debugging process go way quicker.
Gradle isn’t black magic: it’s a tool like any other: Gradle’s syntax can be funky and hard to understand, but it’s still just a whole bunch of code that’s running. Understanding how Gradle resolves dependencies and how its syntax works can go a long way towards solving your build woes.
Make sure you understand the code you're copying from StackOverflow: There are a lot of solutions to Gradle problems which involve slapping together some poorly understood answer on StackOverflow. This leads to Gradle continuing to feel like Black Magic. Make sure to take the time to understand what this solution that someone suggested is actually doing before adding it into your codebase. One great way I've found to do this is instead of copying and pasting code, take the time to write it yourself.

A/B Testing From The Ground Up At Droidcon SF

2017-11-04T00:00:00+00:00

I recently had a chance to talk about A/B testing at Droidcon SF as part of a talk called "A/B Testing From The Ground Up". The goal with this talk was to give attendees an overview of all the moving parts needed to get an A/B test up and running on mobile. The video should be up in a couple of weeks. In the meantime, the slides for the talk are below.

Multiplying Your Impact Through Mentoring at Droicon UK

2017-10-27T00:00:00+00:00

I recently presented a new and improved version of my talk on "Multiplying Your Impact Through Mentoring" presentation, this time at Droidcon London. A friend at Yelp suggests that the third time is the best time for any presentation, and after the fourth presentation it's time to retire the talk. I definitely felt like that was true this time, so I just need to find one last time to present this talk and ride off into the sunset.

The video recording is also really well done, and you can watch that atthe official Droidcon UK website

The Benefits of Shipping Code In Small Chunks

2017-09-30T00:00:00+00:00

One of the more unintuitive things in professional software development is the idea that you should break your code up into small, fully functioning chunks, rather than shipping it all as one big change. After all, wouldn’t more changes mean more code reviews, more pushes, and more opportunities for production to break, all of which slow down the time spent actually building useful features? Yes, shipping more changes does absolutely require doing more of all the above. However, it also has a myriad of benefits which make it the better and more scalable, approach to shipping code.

Shipping small changes helps you ship code faster

Every change you make adds complexity into your system: the larger the change, the more complexity it is likely adding to your system. This complexity comes in two forms: the obvious complexity of the new lines code you’re adding, and also the more insidious complexity of how each part of that change interacts with the rest of the system.

In software, any one mistake can break our system, so anyone responsible for reviewing your code must both understand all the new code and also how it interacts with the existing system before they’re able to provide effective feedback and approval. This need for context building slows down code review feedback cycles and means that you to wait longer for your change to be fully reviewed. Every second of this review is a second you lose context on the code you wrote, meaning the longer you have to wait for a code review, the longer it will take you to respond to that feedback.

If you ship code in small changesets you avoid this productivity pit by making shipping new features in smaller, more well understood steps. This helps your reviewers quickly understand your code and provide effective feedback and saves you from having to rebuild context on the code you wrote. The end result: faster code reviews, faster approvals, and faster changes shipped to production.

Shipping Small Changes Means Wrangling With Version Control Less Frequently

Large changes take a long time to implement, test, and review before they can ultimately be merged into master. While this is happening, the rest of your team isn’t standing still: they’re working on shipping their own features, some of which may be changing code you depend on. Similarly, you may be changing code that your teammates are depending on for their own feature to work.

Unfortunately, these dependencies between these on these features is silent, and you’ll only see your teammates changes when you merge with their branch, and visa versa. Doing this regularly with multiple feature branches quickly becomes a headache, and you’ll find yourself wishing for a better way to make sure people are not adversely affected by others’ work.

Fortunately, there’s an easy way to do this: have small changes that you continually merge into master. This workflow improves this situation for everyone involved. You benefit because your feature is constantly being built off the latest changes in master, meaning you’re not surprised by a merge conflict, and your teammates get consistent visibility into how your feature is changing the code base, so their world doesn’t get changed out from under them. It’s a win-win for everyone!

Smaller changes represent smaller, more reversible decisions.

If you have a change that implements a large feature from in one big bang commit, it represents a lot of decisions about the future of your codebase. For example, a fully functioning backend API endpoint may include decisions about your database tables, how the business logic should be architected, and ultimately about the public API your service will expose.

Tying all these decisions together in one large change means that you’ve coupled all these decisions together, and a change in any one may result in you having to rework large parts of your feature even after you thought it was “done”. This is no bueno both in terms of your own happiness and making you the most productive.

You can avoid this conundrum by shipping your code in small changes which make small decisions that validate any assumptions you have and give any additional information. If your decision is validated, awesome, you can go and build out the next piece of your feature. However, it turned out to be bad, then you don’t have many sunk costs, so it’s easy to revert that change and do it better the next time.

Shipping small changes forces you learn how to manage large projects

Project management is a different game than just writing code yourself. While writing code solo is an exercise in design and implementation, project management is a constant game of managing dependencies, scoping out work, and figuring out what things your team can do to keep moving forward while their dependencies fall into place.

When you ship features as small changes, you learn to do exactly this. You understand the end state, take a look at what you have now, and figure out where you can slice off a logical piece of functionality to ship. This forces you to learn how to simplify an ambiguous task into logical components, ship components which unblock future work, and manage dependencies between your code reviews to make sure that you never block yourself.

If you start building the skills starting from your smallest changes, then managing a large project with multiple developers is not a foreign skill set to master. Instead, it’s just a matter of using the same skills you’ve already learned, but applying them on a larger scale.

Like many other things, shipping your code in small changes is not a panacea which will solve all your development woes. Just because your code goes to production 300 lines at a time doesn’t mean that you’ll suddenly have no bugs and there won’t be any overhead in coordinating between your team. However, it does do is create a process which allows teams to regularly and safely deploy code to production while minimizing the amount of time spent stepping on each others’ toes. I think that’s something we can all agree is a good thing.

Discussions on Building Widely Adopted Infrsatructure

2017-08-09T00:00:00+00:00

Every month, a group of engineers at Yelp get together for something we call the "technical roundtable", which is basically a big discussion group on technical topics that are challenging the company. Often, these focus on specific pieces of Yelp's technical infrastructure, but our most recent one touched on time management for mid-level to senior engineers. A lot of the takeaways were initially surprising but obvious in retrospect, so I figured I'd share them with the wider internet.

First, one of our engineering managers talked about the concept of important vs. urgent, which is a common guiding framework for making sure you don't fall into the busyness trap. He also discussed leveraging your time, which Edmund Lau covers really effectively in his book The Effective Engineer. Both of these are useful frameworks, but you can just go read the primary sources to find out more about them.

One interesting concept he touched was the idea of giving up responsibilities as a way to foster organizational health. The basic idea is this: over time it's easy to accumulate a bunch of small, disparate responsibilities like running learning groups which benefit your team/company but are not central to your core job of shipping software. It can be tempting to keep these responsibilities forever, after all, you have the most context on them, and it seems like anyone else who picked them up would only do 80% as well.

Our presenter argued that these types of low-leverage activities are exactly the things that you should be giving up to more junior engineers to help them grow. First and foremost, it frees up your time, so yu can focus on higher-leverage activities for yourself. Second, it'll be a stretch for them, which means that they'll gain new skills and become more productive members of your team. Finally, they'll be able to spend more time focused on that task, so it'll probably get done better in the long run. He closed with a quote from our old SVP who would always ask "can they do it 80% as well as you now? If so, they'll be doing it 120% as well as you in a month", which I felt really succinctly sums up the idea.

The second part of the event was a "point/counterpoint" disccussion, where a variety of engineers got together to discuss the pros/cons of spending our time in various ways. I got placed into the "writing code" breakout group, where one of our infrastructure engineers suggested that it isn't a question of writing too much/too little code, but rather writing the right code and reusing infrastructure where appropriate. This became a question of "how do we make sure everyone knows about the tools that they can reuse so they don't build their own custom solution?"

We discussed the contours of this problem and came up with a few ways to deal with it that feel generally applicable:

If you're trying to build a piece of infrastructure that will be generally useful, you have to understand other engineers' problems/needs. Very often it's easy to solve our particular version of the problem in a clean, maintainable way, but ignore edge cases that may be important to other developers. This is fine if you just want a one-off solution, but if you want to make some truly reusable systems, it's important to put your PM hat on and understand your users' (i.e other engineers') needs before implementing a solution.
Any piece of infrastructure needs to solve its problem exceptionally well. This is rooted in the idea that it's generally hard to go modify some code you don't have context on rather than building a system from scratch. If an individual developer is confronted with the choice of "go modify someone else's 60% solution that to make it fit my use case" vs. "Go write a 60% solution which solves my own problems" it may just be quicker to write the whole thing from scratch. However, if that same system solves 95% of her hard problems , it's much more likely that the same developer will do some up-front work to just use what exists.
Finally, and perhaps most surprisingly, we all agreed that it's important to make sure you have a PR push to make other engineers aware of what you've built. On a small team, this can be as simple as an email + message to your Slack channel saying "hey, did you know about this cool new thing we have", but that probably isn't sufficient when you have a team of engineers getting innundated with emails. Our most successful infrastructure projects have built a critical mass of support by going out and showing other people how it solves their use case, building out features and documentation in the process. In this way, things like our Data Pipeline have built a critical mass of awareness such that the first thing people think of when they're trying to stream data across Yelp.

A lot of these ideas feel really obvious in retrospect, but it's also really easy to fall into the trap of producing another 60% solution to that just solves your team's version of a problem. It seems like the best solution we've found as an industry is to have infrastructure teams who are incentivized to serve internal developers combined with feature teams which use those tools and make a judgement call about whether they should build something generally applicable or something which just fits their use case. This approach seems to help us get along, but doesn't feel perfect, and I'd love to hear if there are any large software teams which strike this balance really well.

Ship Great Apps Faster By Collaborating With Designers

2017-07-04T00:00:00+00:00

Whenever I hangout with mobile developers at meetups, I hear a bunch of misconceptions tossed around, but one of the most pernicious is the belief that designers are head-in-the-clouds artists, throwing pixels around without concern for what it will mean to implement their creation. On the surface, this comparison is apt; both artists and designers create visual artifacts out of ink, paper, and pixels. Dig a little deeper into what designers do every day though, and you will discover that that design is not art. Rather, design is a problem solving discipline which tackles a different, but complementary, set of problems to the ones engineers solve when creating a product. Once engineers internalize this idea of designers as problem solvers and not artists, it opens up a whole new mode of collaboration which allows for otherwise impossible products to be shipped.

Unfortunately, most product and engineering teams operate in a way which makes building this type of understanding difficult. Many teams make problem definition and ideation solely the realm of designers and product managers with engineers only getting involved once a mock-up is mostly finalized.

In this world, it’s easy to see why engineers see designers as artists and not problem solvers. If all an engineer sees is a Sketch file with some redlines, it’s easy to be blind to all the work that went into figuring out what to put on the design, and instead focus on the pixel massaging necessary to make it look good.

This process failure isn’t a problem in the happy path of product development: designers propose solutions which fit easily within the platform constraints, and engineers are able to implement them with some light back and forth. Unfortunately, very few mock-ups can be implemented on this happy path. Maybe the mock-up proposes adding a bunch of custom one-off dimensions to the layout, which will make it hard to maintain in the future. Or perhaps there’s an animation which seems simple, but would actually take weeks to implement (I’m looking at you, keyboard animations on Android). What’s a team to do in this case?

The choice I hear all too frequently is to push-and-pull until one side “wins”. Either the design is implemented as-is, regardless of platform standards and technical debt incurred, or the feature gets axed as “technically infeasible”. This type of thinking is a classic example of positional bargaining, with designers and engineers negotiating against each other about what the final product should look like. Both of these miss the point though, as what they should really be asking is “what are we trying to solve in the first place, and how can we build a solution which gets us there in the best way possible?”

Once the problem has been reframed that way then folks on both sides of the table can start to work together to make it a reality. Animations can be changed, dimensions tweaked, and platform-specific widgets can be used to replace the custom solution that was initially designed. All of these changes work together to create a product that solves the same problems for users, but can be shipped faster and with more maintainable code.

This promised land of faster shipping, happier teams, and satisfied users sounds great, but getting to this type of collaboration does not happen overnight. It requires a large amount of education for both designers and developers so that they can understand the impacts of ignoring the others’ concerns.

Fortunately, Google has started shouldering some of the burden by doing an all-out Material design education push. This has helped designers understand the principles behind how to build beautiful Android applications, and it has helped engineers understand the types of problems their design teams aim to solve day-in and day-out. At the same time, the Material guidelines are just that: guidelines; sometimes they will need to be bent, or even broken in order to solve a particular problem. In those cases, there is no substitute for engineers and designers understanding some core principles of how the other discipline works.

So if you’re an engineer, and you encounter a design which seems like it has some unforeseen technical consequences, take time to talk about those challenges and the impact they’ll have on your project. And if you’re a designer sharing a mock-up, don’t throw some redlines on a sketch file and assume your engineers will understand ideas like grouping, and consistency; take time to educate engineering teams on the “why’s” of a particular design, including some of the fundamental principles they may not even be aware of. You may just be surprised at the end result.

Curious of what this looks like in action?

When we redesigned the Yelp Android application in 2014, all the mock-ups called for bottom tabs even though the Android design guidelines specifically told us not to do it. Our engineers read those design guidelines and expressed concerns about the mock-ups the design team, citing concerns about platform. Our design team listened to our concerns, explained why we wanted persistent tabs in the application, and showed all of the other possible iterations, along with an explanation about why something like top tabs (which were standard at the time) were insufficient. At the same time, the initial mock-ups called for those tabs to stay consistent, but the screen content would still animate. We tried A LOT of different ways to make this happen, but short of rewriting the whole app to use Fragments (which would’ve been a mammoth undertaking), or doing some janky UI tricks on every Activity, we couldn’t figure out how to make this happen. As a result, we decided to just remove transitions entirely from our app. We were all bummed that we couldn’t get the type of beautiful transitions that we initially wanted, but we delivered the most important parts of the design and didn’t build a mountain of technical debt.

A big thanks goes out to Briana Como and Ramya Mallya, both of whom helped tremendously in providing context and editing for the thoughts here.

Multiplying Your Impact Through Mentoring at Chicago Roboto

2017-04-20T00:00:00+00:00

I recently presented an updated version of my "Multiplying Your Impact Through Mentoring" presentation at Chicago Roboto. The audience had some really great questions which made me realize I need to think more deeply about some aspects of mentoring and update my presentation the next time around. The slides that I presented are below

Effective Interviewing Through Storytelling

2017-03-23T00:00:00+00:00

This weekend I had the pleasure of getting to attend the AI In Action Spring 2017 hackathon at Claflin University in Orangeburg South Carolina. AI in Action focuses on empowering K-12 students in rural South Carolina by teaching them to code. While I was there I gave a presentation on an aspect of interviewing that I think is really under-coached: communication. These are the slides from that presentation.

Supercharging your Code Review With Collaboration

2017-03-14T00:00:00+00:00

Software engineers always talk about how code reviews are the single biggest thing to improve your code quality, but we often forget that putting your hard-written code up for review can be scary. We invest a lot of time in making sure that our code is perfect, so submitting it to someone for their critique can feel like putting part of our identity up for critique.

Fortunately for you, prospective code reviewer, there’s something you can do to help. By being conscious of the language you use when suggesting revisions, you can preemptively allay the concerns of your reviewee and supercharge your code reviews. Best of all, it only requires tweaking a few phrases in your vocabulary.

Getting started: Focus your critical feedback on the code, not the people who wrote the code.

One of the first keys to building safety as a reviewer is to make it clear that any feedback you give is not about the code’s author, but rather a comment on the code itself. This can seem complicated, but there’s a dead simple way to get started accomplishing this: remove the word “you” from your code review vocabulary.

It’s a little challenging to get started with this new, you-free lifestyle, but you’ll find that it pays huge dividends. In fact, once you’re aware of it, you’ll find the sneaky three letter word has been cropping up all over the place, making situations adversarial when they should feel collaborative. Worst of all, chances are, your “you’s” have probably been popping up when they’ve actually been referring to the code all along!

Let’s take a look at a fairly innocuous code review comment:

“You’ve really tightly coupled your classes here. That may cause some problems down the road.”

My heart skips a little when I read that, and I’m not even the one who wrote the code! By immediately focusing on “you”, this comment can speak right to the little voice which says “I’m no good because my code is no good”. Once that little voice starts to talk, conversational safety starts to go out the window, and it’s taking collaboration right along with it.

Fortunately, in many cases, if you do a mental find/replace for “you” with “the code”, you get something much more collaboration friendly, like:

“This code here looks really tightly coupled. That may cause some problems down the road”

Phew! Look at how much chest-tightness that eliminated. This comment no longer references the code review author at all, and instead it only focuses on something much more objective: the code itself. Now that we’ve shifted that focus, we can employ a couple more techniques to make others receptive to your feed back.

Next Up: Think of your comments as suggestions, not dictations

No one likes to be told what to do, and code review is no exception to this. At the same time, one of your responsibilities as a reviewer is to get your reviewee’s code to a place that your team is comfortable shipping it, which sometimes requires getting them to change things they may feel attached to.

How to resolve this tension? Try not to make your comments dictations but rather suggestions which open up space for discussion. To look at how we can do this, let’s continue with our well-intentioned feedback from above, but this time with a slight modification.

“The code here looks really tightly coupled. It should be refactored into class A and Class B”

This statement scores high marks for focusing on the code, but it could use some improvement in the collaboration department by dictating the solution to a problem. This comment may be correct, but it pushes the discussion into a realm where it may seem like you’re forced to make the fool’s choice. If the only options presented are “keep the code as it stands” or “take your reviewer’s suggestion” then there’s not an obvious space to agree with the premise (tight coupling) but propose a new solution.

Much like our safety-building find/replace, the way to avoid this trap is fairly simple: rephrase your suggestion from a dictation to a question about a particular direction. Applying that transformation to our above comment, we get a comment that looks like:

“The code here looks really tightly coupled. What if it got refactored it into class A and class B?”

Holy moly! What a difference three words and a punctuation change makes! Instantly upon reading this question, you probably started trying to answer this question in your head, and we don’t even have anything real to refactor! Just imagine if we were talking about a real code review!

Maybe the end result of this is that you move in the suggested direction, maybe you don’t do anything, or maybe you find some third path that makes everyone satisfied. Regardless of the direction, what was once a code review commandment is now a full-blown code review collaboration.

But we’re not done yet, there’s still a final form that our code review can evolve into, and all we need to do to make that happen is use one simple word.

Look for places to use “we” instead of “you”

We talked above about how and why to avoid using “you” in code reviews, but really we only suggested one possible other direction: talking about the code directly. What’s a code reviewer to do when they actually need to refer to a person then? In those cases, save yourself a character and swap your “you”s for “we”

This matters because we live in a world of collective code ownership, which means that any code that your teammate puts into production immediately becomes everyone’s responsibility. If a change breaks at 2 AM, Pagerduty isn’t going to take the time to git blame the offending line; it’s going to wake someone up, and that someone may be you.

This means that code review isn’t just a time to make sure that the code is the best it can be. It’s a time to also make sure that it’s code that the whole team is comfortable owning and maintaining. By using “we” in your code reviews, it reminds everyone involved that the goal is creating a great end product for the team. Plus, it’s super simple!

We can take our previous comment:

“The code here looks really tightly coupled. What if it got refactored it into class A and class B?”

And wordsmith it into

“The code here looks tightly coupled, which may come back and bite us down the line when we want to make changes. What if we refactor it now into class A and class B?”.

Wham! Not only have we given a rationale for why we’re suggesting a particular change, but also we’ve communicated it in such a way that it’s clear that both the author and reviewer feel like they’re on the same side. Both parties want flexible, maintainable code, and this comment sets the two of them up to work towards that goal together, rather than as adversaries.

With those three small changes: removing the word “you”, focusing on the code, using “we”, and phrasing suggestions as questions, our code review toolbelt has received a serious level-up. These new tools won’t immediately change how your code review operates, but with continued application you’ll find that an activity which was once an unproductive chore will turn into a valuable opportunity to work with your team to help ship the best possible software.

That’s not a bad outcome for shuffling around a couple of words and changing a punctuation mark.

A big thank you for this post goes out to Or, the best editor-in-chief I know at Yelp, and Carmen, who inspired many of the thoughts here.

Slides From Multiplying Your Impact Through Mentoring

2017-02-05T00:00:00+00:00

I gave my first big boy conference presentation today at DevFest Minnesota! The topic was "Multiplying Your Impact Through Mentoring", which has been rattled around in my head a while because I think we as an industry do a pretty poor job of training mentors. The slides are below.

Asking Great Questions on the Internet

2017-01-27T00:00:00+00:00

We’ve all been there before: you’re chugging away on a technical problem and suddenly you hit a brick wall you just can’t seem to get over. You’ve turned down every imaginable path, but still you’re getting behavior that seems like it was created by some sort of deity just to spite you. Fortunately, there is hope! Many projects, both enterprise and open source, maintain chat channels and mailing lists that you can use to ask questions to get yourself unstuck on your current problem.

However, asking good questions is hard. You need to take everything you’ve tried and learned, word it in such a way that someone else can understand it, and then finally figure out what you actually need to ask to get a helpful answer. Doing all of this effortlessly requires not just communication skills, but also serious empathy skills.

What’s a good engineer to do here? Building up your communication and empathy muscles can take a long time, and chances are you need answers to your questions right. One option is to follow a fairly simple process I teach all my mentees in order to jumpstart their own question asking skills.

The process starts by doing your own research, transitions into defining your problem appropriately, then sharing what you’ve already tried, and finally actually asking a question. I’ve found that by following these four steps, anyone can ask an informed question which puts them on the path to solving their problems.

So what are the specifics? Let’s jump into the details.

Step 0: Do your own research

Collaboration with other engineers is a great tool to help get you unblocked, but remember that others have their own work they want to get done. Because of this, you want to make sure that you’re valuing their time by doing your best to solve your own issues before enlisting the help of others.

Before you go out into the vast wilds of the internet to ask questions, make sure that you’ve read through the relevant documentation, googled for your question, and checked StackOverflow to see if anyone on the internet has already solved your problem.

Once you start going down the research rabbit hole, you may be nagged by the question of “how do I know when I’ve done ‘enough research’”? To that end, I like to follow the mantra of “You must try, then you must ask”, which states that after you feel like you’ve hit a dead-end on a problem, you need to set a timer, work on it for 15 more minutes, and then go ask for help.

Once you’ve done you’ve tried and have not found a solution to your problem, it’s time to go ask for help!

Step 1: Describe what you’re looking to accomplish.

The first step of asking a great question on IRC is actually not to ask any question at all (very zen); the first step is to describe the problem you’re trying to solve. You may be in a rush to get an answer to your specific question, but remember, the person you’re asking has NO IDEA about the ultimate goal you’re trying to accomplish.

This can be the cause of a whole mess of frustration. If you just jump into a channel and ask “How do I fix my failing Foobarnicator?”, someone’s first response may be “Foobarnicators are so 2014, Baznicators are where it’s at now”. Then before you know it you’re in a discussion about Foobarnicators vs. Baznicators when you know Baznicators don’t solve your particular problem.

In order to avoid this conundrum, you want to give the askee sufficient context on the problem you’re trying to solve. “Sufficient Context” can be one of those tricky shifting targets to hit: you don’t want to be too specific, because then you don’t get to leverage your respondent’s domain knowledge to validate your approach. However, you also don’t want to be too general, because then your discussion can easily go off the rails.

In general, I’ve found that there’s a goldilocks zone of specificity that exists right around describing the human-facing goal that you’re trying to achieve. Links to tasks in your bug tracker of choice are a great tool for this (I’ll use JIRA just for example’s sake). For example:

Too Vague: Hey smart person! I’m looking to make some changes to our Android app.

Is probably too broad of a context to set. Android applications can be 100s of thousands of lines of code, so anyone looking to help you is would be throwing darts onto a board the size of Texas, hoping to get a bullseye.

Too Specific: Hey smart person! I’m looking to debug an error on line 56 on the PaymentActivity of our Android app.

This definitely gives people a much smaller idea of what context they need to help you, but it also anchors them to a specific part of the code. If your problem lies elsewhere in the code, both of you will need to take a step back to find the actual solution to the problem.

Just Right: Hey smart person! I’m trying to add a feature to our application which lets us place orders ${JIRA TICKET}. When I send a request to place an order the app crashes!

This provides less detail than the above description, but it gives the person you’re asking a framework for how to think about your problem without pigeonholing them into a solution. Chances are they have a general idea of where your problem may live, so it’s time to take the next step towards an answer.

Step 2: Describe relevant metadata and what you’ve tried so far

Once you’ve framed your question properly, the next thing you want to do is help your helper give you the best advice possible. This means not only explaining what you’ve tried so far, but also preemptively answering common questions that come up when people try to solve your particular problem. The pieces of information you should supply roughly break down into three categories:

1. Your investigation so far. Describe the areas of the code you’ve already explored, why those didn’t work out, and any conclusions that you’ve drawn from those failures. As you’re doing this, be sure to include the actual output of these actions. This can include things like:

API responses
Stacktraces
Log lines that have been printed out

2. Actions you have taken to try to solve the problem. Have you run a clean build? Cleared your cache? Pulled master? Tried that thing your co-worker sent out in an email yesterday? If not, go do those first.

3. Any relevant metadata about your setup that may be important. The necessary information here can vary wildly depending on what you’re working on but the idea is you want to include details like your OS version and device model.

If we were to fully contextualize our question above, it would look something like this.

Hey smart person! I’m trying to add a feature to our application which lets us place orders ${JIRA TICKET}. When I send a request to place an order the app crashes with a stracktrace of ${pastebin link}! I’ve found that after pressing the “order” button the application successfully sends a request to the server with that looks like ${pastebin link}, and receives the response ${pastebin link}. I’ve tried logging out and in and restarting the app but that doesn’t change the behavior . I’m also running Android M on a Google Pixel if that matters.

Holy cow! Our simple statement just became an intimidating block of text. Even the most diligent assistant will have their eyes glaze over looking at that. Eye-glazing is scientifically shown to lead to unhelpful results, so you want to break this message up into multiple messages in quick success to make the content easier to consume. After a quick trip to the line-break machine the previous message becomes something like:

Hey smart person! I’m trying to add a feature to our application which lets us place orders ${JIRA TICKET}. When I send a request to place an order the app crashes with a stracktrace of ${pastebin link}!

I’ve found that after pressing the “order” button the application successfully sends a request to the server with that looks like ${pastebin link}, and receives the response ${pastebin link}.

I’ve tried logging out and in and restarting the app but that doesn’t change the behavior. I’m also running Android M on a Google Pixel if that matters.

Oftentimes, you’ll find that completing this step forces you to think through your problem in a whole new way and gets you a solution to without actually needing to ask a question. However, if you’re still stumped it’s time to take on Step 3!

Step 3: Ask for help in a way that engages others but doesn’t abdicate responsibility.

Once you’ve established the problem you’re trying to solve and what you’ve already tried, it’s time to actually ask for help! A good question has three criteria:

Clarity: A good question will not leave any doubt what information you’re looking for from the person you’re asking.
It actually solves your problem: If you are not able to accomplish your initial goal after getting an answer to your question, then you should head back to the drawing board and ask something that allows you to move forward.
It keeps you in the drivers’ seat of problem solving: Most people are happy to help, but they don’t want to feel like others’ questions are being dumped on them. You want to ask a question which gets others to help you solve your own problem, not one which gets them to solve your problem for you.

Fortunately for you, fair question asker, if you followed through on steps 1 and 2 of this process, you’ll have a pretty clear and actionable question to ask. Oftentimes it will be some form of “Any idea where I should look next to continue debugging this?” or “Does what I just described sound like a sane approach to you?” Both of these are perfectly great questions and allow you to push forward with solving your own problem

Putting all this together, our final question ends up looking something like:

Hey smart person! I’m trying to add a feature to our application which lets us place orders ${JIRA TICKET}. When I send a request to place an order the app crashes with a stracktrace of ${pastebin link}!

I’ve found that after pressing the “order” button the application successfully sends a request to the server with that looks like ${pastebin link}, and receives the response ${pastebin link}.
I’ve tried logging out and in and restarting the app but that doesn’t change the behavior. I’m also running Android M on a Google Pixel if that matters.

I’m kind of at a loss for where to chase this bug next, do you have any suggestions for what I should investigate next?

The above question hits all four of the major things you need. First, it describes a problem that’s neither too specific nor too general, meaning that whoever answers this question will be able to help us without being pigeonholed into a possibly incorrect hypothesis. Next, it gave anyone who answers this enough information about what you tried so they don’t have to spend time asking questions like “have you tried restarting the app?” or “what’s the stack trace?” and can focus on really understanding the problem. Lastly, it contains a question which keeps you in the driver seat, ensuring that you’re consistently collaborating rather than throwing your problems over a fence and hoping they get solved.

After you go through this process a bunch of times, you’ll find that you’ll start to see patterns emerge in how others respond to your own questions, which in turn allows you to ask better questions. This is GREAT, as it means that all of your questions have led to your empathy muscles growing, which over time will allow you to ask better questions and become a more well-rounded engineer.

Of course, this process isn’t fool-proof, so you’ll occasionally find yourself getting answers to questions which are different than what you really need. When that happens, take a step back and make sure everyone involved understands the problem you’re trying to solve and also what’s already been explored. If that doesn’t get you where you want to go, fear not! The internet is stuffed to the gills with great question asking resources. Specifically, I’m a big fan of this post which speaks about some meta-question asking topics and also links to some other fantastic resources.

Happy question asking!

A big thank-you goes out to Or and Coltin, two colleagues whose contributions significantly improved this post.

Making The Most Of Your Internship Slides

2016-09-17T00:00:00+00:00

Over the past weekend I had the pleasure of mentoring at Hack The North in Waterloo, where I gave an updated presentation on how to have an awesome internship/co-op. The slides are live on Speakerdeck.

Slides From How To Have An Awesome Summer Internship

2015-09-29T00:00:00+00:00

Today I had the pleasure of giving a presentation to students at stanford about how they can have a succesful summer internship. These are the slides from that presentation.

Some Tricks To Make You More Productive

2014-06-23T00:00:00+00:00

Every developer has their own little kit of productivity tools which they constantly expand over time. Unfortunately, I've found that the only way these tools get shared is when someone has a problem someone else pipes up "Hey, I know how to do that!", and passes on their tribal knowledge, only for it to be lost until the next person has the same problem. In the spirit of "sharing stuff I wish I'd known last year", I wanted to share some neat things I've discovered over the past couple of months which have helped me solve various problems.

Before getting started, I deliberately haven't gone into the nitty gritty of how this stuff works/is configured. Once you know that most of this stuff exists, actually configuring it is pretty easy.

Git's -w flag

Ever found yourself looking at a git diff and seen hundreds of lines of changes which were only whitespace? Did your team's recent switch from tabs to spaces make git blame useless? If so, it's -w flag to the rescue!

When using git blame, git show, or git diff (and possibly more), the -w flag will ignore whitespace changes, making it easy to find the proper person to yell at for the bug they introduced.

Git log -G

Sometimes you find yourself looking at a file that seems to have undergone all sorts of wacky transformations such that just using git blame/show doesn't tell the full story. What you really need is a full history of that file so you can trace the commits. In these cases, git log -G is what you're looking for.

This command will look through all of the diffs of your commits, and only return those that have a particular string in them. You can use this to look for particular symbols that were modified, or you can just look for file names, as those are also included in diffs. Searching for file names is especially nice because you don't need to put the fully qualified path of the file you want, just the base name will do.

There are also more tools to look through your commit history which give you more fine-grained control over how you search. These two flags are -S and --grep, and the difference between these are summed up nicely in this StackOverflow comment

Configuring /etc/hosts for maximum productivity

If you've done any web development, you're definitely used to configuring virtual hosts by editing your /etc/hosts file. Over the past couple of months though I've started using it for an additional purpose: keeping myself focused. In addition to all of my virtual hosts, I have also re-routed Twitter, Facebook, and Reddit all to localhost.

Before doing this I'd often find myself checking Reddit "just for a minute" and then 30 minutes later I'd be way off track, looking at a bunch of mediocre cat memes. Now, if I want to get on Reddit or Facebook, I need to take a couple of conscious steps to edit my /etc/hosts file and unblock that website.

It isn't too much of a hassle, so I can still easily test stuff like Facebook/Twitter sharing, but it's enough friction that I don't find myself aimlessly wandering to my twitter feed.

Note: this also works really well if you need to study for finals and find yourself constantly distracted by Tetris Friends a la Gerard O'Neill.

Pycharm Remote Debugging

Over at Yelp, all of our API development is done on remote machines. While this solves some infrastructure problems, it also creates some others. One of the biggest, especially for API developers is "how the hell do you debug stuff?" Printing is one option, but sometimes you need something more powerful, and that's where Pycharm remote debugging comes in.

With remote debugging you can insert a couple of lines of code into any file, drop in a breakpoint, and then run my code as normal. Whenever that breakpoint gets hit, the remote code will connect to my local Pycharm instance, and connect to the debugger as if the code was running locally.

Once connected, you can debug the code as if it were running locally. You can step into method calls, examine program state, and drop in further breakpoints just as if your code were running locally. If you're used to visual debuggers from other IDEs this is truly a god-send.

IntelliJ Live Templates

No matter what language you write in, there are always code blocks that you find yourself continually writing. IntelliJ live templates are the end of this. With live templates, you cobble together a bunch of code that you are continually writing (e.g. the 3-line code block which sets up Pycharm remote debugging) and assign it to a shorthand notation.

Next, when you want to drop that particular code block somewhere, you can call up your list of live templates, start typing out your template's assigned name and then get it completed as if it were just another function name.

But wait! In case adding 5-lines of code with 4 keystrokes wasn't enough, you can also customize live templates so that parts of them are variable. This is incredibly useful if you often write something like Log.e(TAG, "random_debug_statement").

By using live templates, you can assign that whole statement to one live template, called LE. Then, when you insert the LE template, your cursor will be put right in the quotes where you'd write your debug statement. You can also go crazy and have live templates with multiple variables and just tab through to insert text where appropriate. You have never felt like such a master of your code.

Those are all the neat little tricks I've picked up for now. Over the next couple of weeks I'll (finally) be digging into Android Studio and Espresso for HN, so hopefully that will lead to all sorts of productivity goodness in the wake of my first Google I/O.

How To Have An Awesome Summer Internship

2014-05-09T00:00:00+00:00

Last week I gave a talk at Rutgers about how to make the most out of your summer internship. Over the past few years I've worked at a fair variety of companies, and I've screwed up a lot in the process. Before heading out into the world of a full-time engineer I wanted to codify some of the lessons that I've learned in hopes that future interns will be able to avoid some of the pitfalls I ran into.

In case you randomly stumbled here and have no idea who I am: Hi! I'm Jonathan. I'm a recent Rutgers grad who now works as an Android engineer at Yelp. When I'm not doing that, I help make a Hacker News reader called HN and occasionally fix up stuff in the Github app. I also stay tuned into Rutgers by helping admin the Rutgers Hackathon Club, a Facebook group where students and alumni hang out.

Before getting started, I want to save people's time by mentioning a couple things that I won't be talking about in these slides. For one, I won't be talking about how to land your dream internship. The reason for that is simple: I don't know how to land your dream internship.

My strategy for getting an internship was to get really good grades and then apply everywhere that would have me. That turned out pretty well for me, but from what I understand that's not The Right Way to get your dream internship. Sadly, I can't speak to The Right Way, but a bunch of other people have written some awesome stuff about it. Check that out at the links above.

The other thing I won't be talking about is how to land a full-time offer after your internship, mostly because I think that's a misguided goal for the summer. Spending your summer focused on getting a full-time offer is putting the horse before the carriage in my mind. Instead, spend your summer focusing on how to improve your skills as a developer and then let good things follow. If you're curious about how to land a full-time offer, ask your recruiter about it, they'll be a way better resource than me anyway.

Cool, now that that's out of the way, time to get into some of the stuff that I will be talking about (the stuff that those puppies are really excited about).

2/3 of what I'll be talking about is inside the workplace stuff: what to expect, what you'll be learning, what to look out for, and how to make the most out of your time as an intern. The other third is stuff that I screwed up and how to avoid that yourself.

With that in mind, I suppose it makes sense to define what exactly makes an awesome internship. For me, the answer to that question is two-fold.

First and foremost, an awesome internship will set you up for a successful career over the long-term. Your first experience as a full-time developer can feel like an overwhelmingly important experience, but in the grand scheme of things it's just one small time slice of a much larger career.

Instead of treating your internship as a make or break moment for your career, look it as another opportunity to improve your craft. Focus on soaking up all the knowledge you can from your teammates and your environment. That way, when you get out of college you'll be able to make a solid decision about where to work full-time.

At the same time, an internship experience be super serious all the time (or arguably ever). During your summer You'll probably be getting paid heaps of money to run around an exciting city, possibly with support from your employer (if they have an official intern program set up). Having an awesome internship is just as much about experiencing the best parts of your temporary home as it is professional development.

Before you get started interning, one thing to realize is that many times during your summer you may feel like a dumb person in a room full of experts. THAT'S OKAY. In fact, that's not only okay, it's expected.

You're probably be put onto a team with a bunch of people who have 5+ years cutting code for a living. It would be ridiculous to expect that you'd rock up and be coding at their level after a month of experience professionally creating software.

You weren't hired with the expectation that you'll put out the same quantity and quality of code as experienced engineers. Rather, you were hired with the expectation that you'll struggle a bit and do some bumbling around before figuring out how things work.

So don't feel bad when you have to ask "how do I submit my code for review", or if it subsequently gets shredded on review. Those types of struggles are TOTALLY NORMAL and are part of the growing process. Even the superhuman senior architect on your team was once there too.

Although you aren't expected to have flawless development skills, you will want to take the opportunity to improve as much as possible and learn as much as possible about how to become a better developer.

The first half of improving your skills as a developer is increasing your knowledge of all the technical stuff that goes into making software. A lot of this will happen organically just because you'll be reading, writing, and getting feedback on lots of code. However, you can also take a couple of steps to supercharge your learning.

First: actually read documentation. By read documentation I don't mean "open up the docs and press CTRL+F". That's not reading documentation, that's playing the blind squirrel hoping to find a nut. I mean actually take the time to sit down and read them until you fully understand them.

It may feel weird and unproductive and weird to spend a full day reading docs. Again, DON'T WORRY, spending 6 hours just reading docs is TOTALLY NORMAL; hell, it's sometimes what you need to do to get your job done. Remember, you aren't expected to know everything when you get there, so the only way you're going to learn stuff is to read.

Secondly: use your mentor to get you unstuck on problems. Chances are you will have a mentor assigned to you, try to figure stuff out on your own, but when you're stuck, ask him or her where to look next.

At the same time, it can be a little bit of a guessing game when to ask your mentor for help and when to dig a little deeper. My general rule is to follow the method outlined in this blog post.

There's also the possibility that you won't have a mentor assigned to you, if that's the case just grab a friendly full-timer and ask them your question. Again, remember that asking questions doesn't make you any less of a developer, we all need help sometimes.

Third: ask your mentor big picture questions that will help you better understand how to develop large-scale systems. These are questions like "how is our X designed? Why is it designed that way? What are some limitations of that?"

One awesome strategy my friend Vaibhav uses to find these questions is to write down any term he hears that he doesn't understand down in a notebook. Then, once or twice a week he'd have lunch with his mentor and just pepper him with questions about his company's technology. Steal that or come up with your own strategy, but whatever you do, figure out a way to learn about software engineering from someone who has been doing it already.

The second class of things to learn during your internship is how you can improve your own tools and workflows.

During the course of your internship, you're going to run into a lot of people who do things differently than you. Constantly be on the lookout for these differences, and try to figure out how to steal the good stuff for your own workflow.

As a rule, if you see someone with something that looks useful, whether it's a cute keyboard shortcut or a random productivity tool, you should ask them what they're using and how it helps them work better. If their method seems like it would solve a problem that you're having, head back to your desk and make a note to try it out.

Don't let this list languish. Block out time every week to improve your own workflows. This time may be spent solving some of your own pain points or it may be figuring out how to use the new hotness that your mentor showed you last week. It may seem like a waste to not spend every hour working on your intern project, but any investment in your productivity now will pay big dividends over the long haul.

The other thing to be on the look-out for are the soft skills that other developers posses. You'll undoubtedly run into people who are awesome communicators and problem solvers. Many people who are great at these two skills have systems or tricks that they use to be great. If you find yourself impressed with how someone communicates, see if you can recognize those systems and incorporate them yourself.

The technical side of things is really only part of what you can learn and get out of your internship. There is also a wealth of non-technical things that you can pick up during your summer which will serve you well.

Once of the biggest things I screwed up during my first two internships was being asocial. I would show up to work, eat lunch at my desk, and then head home every day with barely a peep to my coworkers. Both times this turned out to be a terrible decision, as it resulted in me being burned out and dreading work by the end of my internship.

At Yelp!, I decided to flip the script and actually take some time away from my desk. I joked around with my teammates, played foosball with other interns, and staunchly refused to eat lunch at my desk, even if it meant eating by myself at 3 PM in the park.

The difference was massive. Every day I felt like I had energy to solve problems, and when I started to feel down I could always find someone who could help give my mind a break. Most importantly, I never woke up dreading going into Yelp, which was a huge boost for both my happiness and my productivity.

It can be tempting to spend your entire summer with a laser like focus on your terminal (especially if you're focused on getting a FT offer), but trust me, DON'T DO IT. Not only should be a FT offer not be the focus of your internship, but also you'll be happier and more productive if you step away from the computer every now and again.

Besides learning to take breaks, the most important non-technical thing you can learn during your internship is what matters to you in a company culture. It's easy to think of this as "is a company filled with cool people?", but there's so much more to it than that.

Culture is questions like "is this environment comfortable for me?", "if I feel uncomfortable, do I have an avenue to fix that?", "am I cool when/where/the amount I'm expected to work?”, and many more. One of the best articles I've read on this subject is Where To Work, which gives a great breakdown of the types of cultural values that are universally important.

If your company hits high notes on those types of big picture questions, then you'll have a good time working there even if it isn't filled with your BFFs. However, if you're working with a bunch of "cool people" with unsatisfactory answers to these questions, then it may not turn out well over the long haul.

Whether or not your summer is spent working with cool people, be on the look-out for whether you're working somewhere that has a culture that you fit with. Understand what it means to fit somewhere vs. not fit somewhere, and figure out what questions you can ask of future opportunities to figure out where you'd fit.

Internet blogs are riddled with stories of people who tried to be a 10x engineers and ended up a shell of their former selves. DON'T LET THAT BE YOU THIS SUMMER.

It can be tempting to fall into the trap of "I need to work all the hours to get a full-time offer." If you find yourself thinking this way, ask yourself: If you had to work this much for two years, would you still be happy? If not, then you probably don't want that full-time offer anyway, so killing yourself isn't doing much for you.

There is no magic formula for working sustainably, but as a general rule, you should be trying to work at a pace where you feel like you're able to focus throughout the day. If you find yourself sporting any of the signs in this article it may be time to scale back the number of hours you're working.

Every few months a post appears in /r/AskReddit basically asking "how the hell do I make friends after college?" This question seems silly if you're used to a university setting filled with casual interactions, but it highlights the fact that making friends out of school can be non-trivial, especially if you're starting from scratch.

If you're interning in a city where you have a bunch of friends from college then this probably isn't much of a problem. However, if you're taking an opportunity where you don't know anyone within 50 miles, you're going to have a bit more of a challenge.

Put yourself out there by organizing/attending events with other interns (most companies will have an interns chat room or mailing list, go hang out there. If one doesn't exist, create it). If you're a solo bandito intern at your companies, find local groups that do stuff that you're interested in and start regularly attending those events.

Whatever you do, don't let your summer be characterized by you sitting around in your apartment by yourself. Not only is this a bummer of a way to spend a summer, but your mental health will suffer pretty badly in the process.

So yeah, that's pretty much all my thoughts on internship. I'm sure that I could write another couple hundred words, but most of your eyes have probably glazed over by now, so that wouldn't do much good.

If you have any questions about anything I wrote here, or you just want to tell me that what I wrote was good/misguided/so terrible you can't believe they let me on the Internet, feel free to contact me at one of the links in the second slide. Also, I'll be organizing a couple things with Rutgers Hackathon Club peeps over the summer, so if you want to get in on that let me know.

The Price of Inconsistent Code

2013-12-05T00:00:00+00:00

have You ever read an english essay so riddled with errors its tough to read. i'm not talking your normal run of the mill errors; I'm talking about really systematic misunderstanding of how to use punctation!

If so, and you're reading this blog, then it probably evokes the same emotions as seeing code that looks something like this.


		public int foo_barnicate (int foo, float bar ){
		if (  foo >= 0  ) 
			int baz = bar+foo;
		
		return baz;
	}

	public String barFoonicate(String herp)
	{
		if(herp.isEmpty()) herp+= " derp";

		return herp;
	}

In addition to inspiring blood boiling rage, hopefully both of these examples imposed the same type of cognitive tax on you. You probably found yourself struggling just a little bit to place commas in their proper place, relocate brackets, and make sure that all the whitespace was properly aligned. In short, you were spending energy trying to impose consistency between your mental model of what the text should look like, and what it did look like.

We normally don't think about this idea of consistency when dealing with English. Instead, we think about "English grammar", which are really just a set of rules that English speakers agree on about what makes a proper sentence. This agreement is super helpful, because it means that everyone who is writing or reading English has the same mental model of what the text should look like. Whenever a writer writes English, he or she only needs to follow these rules and anyone who reads English will be able to quickly understand the structure of the text, allowing readers to focus most of their energy on understanding the text's content.

Unfortunately, the programming gods have not been so kind to software developers. Rather of having a well defined set of conventions for punctuation and structure, our languages have structural conventions ranging from the whitespace enforcement of Python to many languages' atitude of "format however you want, I don't care". Many developers have realized this lack of standards leads to readability problems, so they set out to fix it by creating style guides like PSR and PEP-8, and even going so far as to create a language with a built-in formatter (in the case of Go).

All of these tools have been boons for developers who want to read and write consistent code, but they don't solve the fact that developers can ignore every possible guideline and still write correct code. This creates a problem, as it means that every block of code presents the author with a new opportunity to use a new style and break the reader's mental model of how the code should look. When this happens, and code switches between styles at will, programmers reading code don't have the luxury of being able to focus on the substance of the code that they're reading. Instead, they first need to waste energy mentally reshaping the code to a consistent image of how it should look, and only then can they start worrying about understanding its content. What's more, if the inconsistency continues into naming conventions, programmers extending code need they will need to waste even more time hunting down whether they need to call fooBarnicate(), foo_barnicate(), or foobarnicate().

The thing is, avoiding problems like these isn't all that hard, it just requires getting into the habit of writing consistent code. Once you have internalized the idea that consistency is important, all you need to do in order to edit any file is find out "how does this file format {insert code feature here}", and then write their own code in the same manner. No style guide needed!.

Sadly though, if Rutgers is any indication, consistency is simply not part of a CS education; code readability is only covered by briefly mentioning the importance of variable naming and comments. From there, code quality is ignored until jumping to OO-Design, where high level documentation is also briefly touched on.

While these concepts are definitely important, it's a little bit like teaching students vocabulary, saying "hey spelling and punctuation exist" and then jumping to how to write a full essay. Sure, you've given them all the tools to write down their ideas in a well structured essay, but chances are it will give any English teacher a heart attack. Similarly, understanding programming without a mind for consistency leads to people creating code that may be conceptually well structured, but it is unecessarily difficult to read.

This type of code is fine in a classroom environment, where it can be written and thrown away after 48 hours. However, in a team environment, code doesn't just get thrown away, it needs to stay around and be maintained for a (sometimes long) period of time. What this means is that over time, the amount of code that exists will start to build up, and re-writing it to fit one consistent style will start to take more effort, until it becomes impossible without automated tools. If you don't enforce a constistent code style from the start, when the time comes to do maintence, anyone reading your code will first need to spend extra time just wrapping their head around how it looks before actually implementing new features.

So do your future maintainers a favor, and take a couple seconds to minimize code inconsistency while you write. Who knows, your future maintainer could just be you.

From 0-350 In Three Years

2013-11-08T00:00:00+00:00

Back when I first declared my CS major at Rutgers three years ago, the community was a far cry from the vibrant and passionate one that characterizes Rutgers today. When I started, Rutgers computer science was a disparate collection of students who scarcely got together in groups larger than four people.

Since then, the community has grown by leaps and bounds; its members have launched startups, taken second in the inaugural MLH season, and founded both a semi-annual hackathon and a semi-annual tech meetup. Now that I have 1.5 feet out the door at Rutgers, I wanted to take a look what factors came together these past three years to change Rutgers CS from a scattered community to the massive group of developers it is today. In the process, I hope that our success can provide some ideas for people hoping to create a similar culture at their school.

We got a physical space for students to socialize in

When you hear “campus computer labs”, it generally conjures up unappealing images like this:

Although there is a fair amount of that at Rutgers, one of our labs is quite different. A few years back a Rutgers employee named Lars Sorrenson decided to convert one of our CS labs into a collaborative learning space. The result was the CAVE, a CS lab which looks something like this:

Although the CAVE isn’t exactly a productive work environment, its design has made the room a CS community hub at Rutgers. The CAVE serves as a great place for workshops and tutoring, but its most important role is as a place for students to meet and hangout between classes. Sometimes they’ll discuss programming, but other times they will just play video games or watch the latest Game of Thrones episode on the giant TV. Through it all, familiar faces from class become acquaintances, acquaintances become friends, and those friendships form the basis for a strong community of developers at Rutgers.

What any university can do: Create a comfortable physical space for students to hang out in and get to know each other. If you can convert an old computer lab, that’s great; if not, try looking for other options to get people in the same space together.

HackRU was started and held regularly

Although now there are a fair number of Rutgers students who regularly travel to hackathons, three years ago you would have been pressed to find more than a handful who even knew what a hackathon was. HackRU initially started out as a modest attempt to grow this small handful, but since then it has grown to engage 250+ students every semester. In the process, it has helped hugely in building community by bringing hacker culture to students at Rutgers.

As the attendance at HackRU demonstrates, there is a large group of students who are either too busy, too intimidated, or simply unaware of hackathons that are going on around the country. By creating an on-campus hackathon, the organizers of HackRU have been able to bring these students together and get them excited about building projects in a way that didn’t happen before. This is not only awesome because it grows the skills of young developers, but also because it shows all the attendees that they’re a part of a larger Rutgers developer community.

What any university can do: Throw a hackathon at your school, no matter where you are. Start by targeting just students at your university and then grow it from there. If you don’t think it’s worthwhile, have a look at what a HackMIT organizer had to say about her experiences.

We created culture based on learning and positivity

Tess Rinearson wrote an awesome article a while back about how CS is a community that is focused on building each other up, and we’ve tried to make that very evident at Rutgers. As many community leaders have grown and become more skilled, they have started to focus on helping underclassmen improve their skills and encouraging them to work on side projects.

From their very first CS course, students are introduced to the idea that Rutgers CS is a helpful community of students by the peer mentoring program. Through this, upperclassmen are put in charge of running small recitations for CS 111, our Intro to CS course at Rutgers. In addition to helping take some of the load off department TAs and establishing a precedent of helpfulness, the peer leader program has served as a great way for upperclassmen to bring underclassmen into the CS community without them having to attend events.

Over the past three years, the spirit of that program has been taken up and broadened by a couple of on campus organizations dedicated to helping students build their programming skills outside the classroom. One such organization, RUMAD has done this by helping students build mobile applications, a process which includes hands-on workshops and presentations about the latest technology. Another organization called USACS has been offering mentoring, tutoring sessions, and a weekly Hacker Hour series to teach students about topics they wouldn’t learn in class. At the same time, RU Tech Meetup and the Rutgers Hackathon Club have also sprung up as avenues for students to get together and show off what they built, thus furthering the idea that students can, and should, get together to build projects on their own.

Taken together, these efforts haven’t produced a development utopia at Rutgers, but they have produced a community of students who are eager to grow their skills and help others do the same.

What any university can do: Create mentorship programs to encourage young developers and help them feel comfortable. Also, create opportunities where people can be recognized for their hard work.

Leaders stepped up and built organizations which brought people together

One of the biggest problems that faced the Rutgers technology community when I joined was that it lacked leaders who took the initiative in building it. All that has changed over the last 3 years as a handful of leaders have emerged to drive the community to its current state.

The proto-leaders in this sense were V and Sameen, two of the big architects behind HackRU, but they aren’t the only ones. Since HackRU 1, many leaders have stepped up and left a legacy of building community at Rutgers. On the USACS side, after V and Sameen stepped down, Devon served as president and brought his own brand of creativity to the table, and now Billy Lynch is doing the same with his presidency at USACS.

At the same time, leadership has expanded past USACS in the form of Swift, who has set the gold standard helping Rutgers students even after graduation, and the RUMAD team: Nis, Dave, and co., all of whom have taken RUMAD from nothing to a 200+ person club in just two years. Without the contributions of these and many other leaders, it is tough to say what the Rutgers community would look like today. However, what’s for sure is that because of these students’ hard-work in building events and organizations, Rutgers technologists have been able to come together in a way that was unheard of 3 years ago.

What any university can do: If you feel like your school needs to have a larger community, start planning events you’d want to attend and then market the hell out of them. Communities don’t just magically appear from thin air, it takes people to build them.

Looking back at the past three years, it’s pretty amazing to see what how much the CS culture at Rutgers has grown. While we haven’t built a development paradise, we have taken a community of 10 students and transformed into a group of 350+ developers who are energized about building new projects. Sadly my time as a Rutgers CS undergrad is coming to an end, so I won’t be able to shape the future of the undergrad community anymore. Nonetheless, I’ll be back as an alumnus over the coming years, and I’m excited to see how future students find ways to grow the Rutgers developer community even further.

This initially appearedon Medium

Getting The Most out of your First Hackathon

2013-10-07T00:00:00+00:00

It’s no secret that over the past three years hackathons have exploded across the country, bringing with them the opportunity for thousands of students to grow their coding skills and build a community of developers at their university. Despite this massive growth, it seems that hackathon knowledge is still spread by word of mouth, leaving some younger students wondering how to get started.

Every couple of months a new student will pop into our Rutgers Hackathon Club Facebook group and ask “I’m only a freshman, can I still join and be successful?” (yes, you can), “I only know [INTRO TO CS LANGUAGE], can I still make something?” (yes, you can) or “how do I know what project to work on while I’m there?” (more on that later). Although much of this is tribal knowledge among veterans, no one has taken the time to codify how newcomers get the most out of their experience. To that end, I’ve put together a dead simple list of everything a first time attendee needs to do so as to maximize their initial hackathon.

Read up a little bit (optional)

For a coding newbie, your first event can definitely be an intimidating experience. People will be throwing around terms like RESTful API, JSON, NoSQL, and client library like they’re the most natural thing in the world. Meanwhile, you’re sitting at API demos hoping wondering how the hell to get a webpage displayed on localhost (or even wondering what the hell this magic localhost is).

If you want to spend your time developing software instead of learning concepts, a little reading goes a long way. Being able to cite the HTTP spec backwards (or even knowing what it is) certainly isn’t necessary, but if you want to build a webapp, knowing about HTTP requests and responses will save you a lot of conceptual headache. Similarly, if you want to build a mobile app, hello worlding an app in your simulator before the hackathon will save you a lot of headache on the day of the event.

If you’re not sure where to start learning some of the subjects discussed above, there are a ton of tutorials out about utilizing APIs for the web, with the first link there in particular being highly recommended. It’s written in Python, but reading the code should be pretty straightforward for anyone with programming knowledge. If you are looking to do something more mobile-based, the docs for starting Android development and iPhone development are also ridiculously extensive.

Even if you decide not to do any reading beforehand, there will assuredly be tech talks and mentorship to get you up to speed with the basic terminology, so don’t let a lack of background knowledge stop you from attending.

Known what you want to accomplish

This can be as simple or as vague as you’d like, but it’s always good to have some type of plan about what you want to accomplish during your 24-48 hours. Your goal can be something as simple as finish and demo SOMETHING, or it can be as detailed as “build a game on Android where squirrels fly through the air and eat exploding acorns”.

If you’re coming to a hackathon with the goal of learning but don’t know what you want to learn, just pick a random language (Python and PHP are easiest for webapps) and plan to make an application that uses that language. Alternatively, if you’re stuck on an application idea, watch the API demos and see if any of the APIs helps solve a problem that you’ve encountered. If you’re still stumped on a project, head to the event’s pitch session and join a team that seems like it has an awesome idea, there will be tons of teams there that would love to have your help.

While we’re on the subject of teams, I want to address one of the most common questions I see in the Rutgers Hackathon Club: “Do I need to go with a team already in place?”. The answer to that is no, not at all. In fact, you don’t even need to want to work with a team; it is perfectly acceptable for you to go solo-bandito and work by yourself. If coding solo that’s not your cup of tea, there are also plenty of ways to join or create a team on site. For your first time, the easiest way to deal with teams is either head in with an idea of some people you’d like to work with (it doesn’t have a codified team, just 4-5 people you could envision yourself working with), plan to work solo or plan to jump on board with someone else’s team. There is also the option of trying to build and lead a team of strangers on-site, however, unless you have experience with this, I’d advise against trying to lead a team of strangers that you met at the event, simply because working with new people always adds a bunch of layers of complexity.

Whatever your team and your goal, make sure to push your skills as a developer. Hackathons are a unique opportunity to have tons of mentorship at your fingertips; take advantage of that by trying something hard and getting extra help as necessary.

Talk to people

You’re probably coming to this event to code, but that doesn’t mean that you need to spend all of your time creating features and debugging errors; you should also spend some time getting to know the other students attending the event. Hackathons are frequented immense community of students and mentors who travel to events multiple times a month, exchange ideas, and generally share their passion for making awesome technology. By taking time out of your hackathon to meet other attendees, you will not only make some great friends, but also you will find opportunities to learn more about programming, get resources for your hack, and even find internships/jobs that you otherwise wouldn’t have known about,

Granted, if this is your first time at a hackathon, the prospect of making new friends in a sea of 1,000 people could seem like a daunting task. If you’re a bit overwhelmed with how to get started meeting other hackathon attendees, try one of these two ideas to get you started.

Go with your school/friends. Chances are your school has a group of students who are interested in programming outside of the classroom, seek them out at your school CS lab, see what events they’re going to, and then join them for those events. If you’re not sure what to look for, just listen for passionate debates about technology. If the students involved do already regularly attend Hackathons, they will certainly be interested in traveling to one with you. Regardless of how you find fellow hackers, don’t be shy about being new, I can guarantee you that your fellow developers would love to share their passion for technology with you. If you’re on the Eastern seaboard and don’t have a group of hackers at your school, drop me a line at @maltzj, I’ll see if I can get you integrated with our network of Rutgers students.
Once you’re at the event, wait for a little while and find someone who looks like they’re taking a break, walk over to them and ask them what they’re working on. 99 times out of 100 he or she will start excitedly talking to your about his or her team’s project. Ask some questions about themselves, their school, and technology that they’re using. Then, get their name, and wish them good luck. If you see that person again, check up on how their project is doing or congratulate them on an awesome presentation if it’s after demos.

After the event, if you feel like the you got along with someone, exchange contact information (business cards and twitter are great for this), stay in touch with your new friend via the interwebs, and catch up at events throughout the year. Congratulations, you just made a friend and “networked”, that wasn’t such an icky and soulless process was it?

Always, always demo.

At the end of every event there will be a period where everyone who attended can show off what they built to the other attendees. No matter how far along your project is, demo SOMETHING. Seriously, even if it is a concept and half a webpage, you should demo it. For the last 24-48 hours you’ve worked hard to build something that you would have thought impossible at the beginning of the event. You deserve to have your hard work rewarded, if not with a prize, then at least with a round of applause from your peers. In case you’re thinking that you shouldn’t demo, let me share a story which changed the way I looked at demoing forever.

My first hackathon was the Spring Penapps in 2012. After starting off with a ton of energy, the event turned into a disaster which culminated in my team and I making a project called “Easy Mood”, a website sort of like rainy mood but way uglier and with kittens (side note: when in doubt, use kittens and gifs). When demo time approached, I was feeling pretty ashamed our project and didn’t want to submit it for presentation. At around the same time, Rutgers Hackathon club founder and Major League Hacking Commissioner, Swift, was walking around talking to the Rutgers contingent about what they did.

He came over, asked our team what we did, and I sheepishly explained our project while confiding that I didn’t really want to present. As soon as the words left my mouth he said, in classic Swift fashion (with slightly choicer language) “Jonathan, I don’t care what you say, you’re presenting”. This was immediately followed by a Swifttastic tirade in which he simultaneously browbeat me into presenting while giving me enough confidence to do so. It was really quite impressive. After that pep talk we decided that there was really no downside to presenting our project, so we went up their and sold Easy Mood as best we could. It just so happened that we were the only team to use a Mashery API, so one of my teammates ended up walking home with a Jambox, a $200 piece of hardware. Not bad for a group that was going to hide in the audience not more than 30 minutes prior.

If that isn’t enough for you, think about this: at some point in your life you’re going to have to sell the idea that something is awesome. Maybe that something will be a product that your company produces, or maybe it will be yourself when an interviewer asks “Sally, tell me about this here project on your resume”. Regardless of what you’re selling, in moments like those you need to know how to take something and make someone else understand why it is awesome. Hackathon demos are the best time to hone that skill because no matter what happens, you have a supportive audience who will cheer you on even if your demo is a catastrophic failure.

Wrapping Up

So that’s it, that’s all you need to do in order to get the most out of your Hackathon experience. You don’t need god-like web programming skills and you don’t need to be able to know 10 different programming languages. Instead, all you need to do is show up to the event with a positive attitude and follow the four simple actions I outlined above. If you do that, you’ll walk out of your first hackathon with a whole raft of new skills and some new friends to boot.

This post initially appeared on the Major League Hacking blog.