I call these docs CRSP (pronounced 'crisp').

C - Context

R - Requirements (or problem statement)

S - Solution space (enumeration of alternative paths)

P - People (audience for the doc)

Traditional architectural design docs are big with a lot of boiler plate, requiring the writer to dot all their Is and cross all their Ts. This ends up taking a lot of time - rightly so if we are working on major changes or new features. But we don't need to be so excruciatingly thorough for most mundane changes. Wouldn't it be nice if we were able to be more crisp? Enter CRSP docs!

The idea behind CRSP docs is to allow the engineer to take a pause before writing code, get all the context, understand the requirements / problem statement and list out a few solutions that can help get us there. The most important thing is to get buy-in from the team (other engineers who will also review the code in the future, Product Managers, Designers, etc). Buy-in at this stage helps align everyone, and things usually move fast once everyone is aligned on what is going on.

As code base size increases it is impossible for just one person to have everything in their heads. With a CRSP doc in your hands, you will be able to solicit feedback from others in the team who might know more about that specific area of the code where you are proposing changes. They might be able to direct you in the right direction and avoid pitfalls.

You might think that writing such a doc for simple changes seems like a waste of time? However, I agree with this comment, any code written without a CRSP doc (or architectural doc) is somewhat speculative. And risks being caught in a spiraling long code review process or worse, cause bugs in production. "Wasting" 30 mins on a CRSP doc can save many many hours in the code writing / review process.

Another reason to have an instinct toward writing a CRSP doc is that it helps bring order to chaos. Often times the requirements are not well defined. Writing what you known in the moment, and then using the members of your team offer comments / feedback can help you firm up the requirements. This forces cross functional partners such as Product Managers or Designers to also structure their thinking and provide inputs.

Once you have firmed up requirements and got team members to buy-in you have the added advantage of being able to refer back to the CRSP doc as you set about to code up the solution. Actually, in all honestly, the CRSP docs are for yourself much more than they are for anyone else in the team.

Velocity is ultimately a function of speed and direction. Having a lot of speed in the wrong direction is as useless as having very low speed. CRSP docs allow you to gain speed in the right direction.

Do you have any similar docs that you write before starting to code? Have they been helpful? Please send them my way (slide into my DMs on twitter) and I can attach them with this post to help others as well.

Yet, in my short experience of the last 15 years in the industry across numerous teams I have found one feature constant among the top performers. Their number of commits (or pull requests) is consistently higher than most of their team mates. In fact in most instances the top performer's commits out number the second highest by 50% or more.

Before we go any further, let’s unpack what “top performer” here means. Every team has their own requirements and what they value most. So top performers take on new meanings depending on the team and circumstances. In this case I define top performers as someone the team considers a go to person for most questions about the code and also can be relied on by PMs to deliver things on time (by their own estimates) and are not afraid to take on challenging projects. Top performers also set a high bar for others to emulate on the team.

A question I asked myself was: why do top performers, as defined above, have the highest commits? Some thoughts that come to mind:

Staging their work

They are good at breaking up large or medium sized work into smaller chunks that are easily reviewable and easier to roll back in case things go south on production. In other words, they know how to "stage" their work. Large commits with a ton of files changed are harder to reviewer and increase scope for bugs to creep in. Smaller pull requests make things easier to review, are more self contained and less risky to ship.

Velocity

They are quick. Overall they display high code velocity. This is not an over-night thing. It takes months and years to become proficient with a codebase. But the more you code, the more you know and the faster you become. It’s a virtuous cycle. You will start out slow, but overtime and with practice you will become fast.

Ownership & Agency

They take on more ownership. If they find an issue along the way, they make a note of it and come back to fix it. Or they might fix in as they go. They leave the codebase better than they found it. And they practice this on a daily basis. They can take on more ownership because of velocity. Since they are quick to begin with, they are able to include improvements and tweaks as part of their regular workflow. They don’t think that “oh here’s an issue, but it’s not my problem”. They own the problem and use their best judgement to solve the problem in the moment. Read more about high agency engineers here.

One might think that being a proficient coder comes with its cons such as being too busy to pair program with others on the team. Or perhaps being interested in solo work and not engaging in helping teammates scale up. On the contrary I have found such prolific coders to be very generous with their time. Their comfort with the code base and speed allows them to carve our good amount of time to help their teammates.

This might indicate some form of Pareto principle at play. Perhaps? I am not sure. I think that if a team functions such that 80% of the output comes from 20% of the people - something is wrong. Using commits as a means of measure output is wrong. I know several world class engineers who do not have the highest number of commits in their team. Yet they are crucial to their teams success. And their output is as valuable or sometimes more valuable than the top committers.

Lastly, if you, as an engineer on a team, find yourself admiring the qualities of the top performer and feel intimidated by them, it might help to figure out the whys behind the how. It’s ok to be intimidated by top performers, and feel a bit lost. But remember that when the top performer started, they too had a learning curve. Those that spend time to learn the “why” behind the “how”, are able to apply that principle across technologies and languages, reaping rich rewards over time.

Hacker News Discussion

I posted this article on Hacker News and it generated a bunch of great discussion. Here are some comments that resonated with me:

The thing to note here is that this is a one-way correlation: top performers tend to produce lots of commits. That does not mean that people who produce a high amount of commits are the top performers in your company. (link)

I have noticed that pretty much every software engineer to some degree has problems that they procrastinate on. Folk can spend 10x more time talking about doing something than it takes to do it. (link)

Fast dev produces 5x more code than normal devs and produces 5x more bugs. Which means the ratio is the same but it feels different because they're producing so much more code. (link)

Defining a Distinguished Engineer by Jessie Frazelle

Jessie talks about what sort of qualities can be found in a “distinguished engineer”. I am not exactly sure our industry has agreed on a common definition of what it means to be a distinguished engineer. But I found that the things she had listed would be good to embody for anyone who wishes to grow in their software career. Here are a few qualities that stuck out to me:

* Being able to give constructive technical criticism: Quite often I find senior engineers giving out solutions to problems and wishing that their team take their word for it. Thats the sign of a lazy senior engineer. A real leader does not expect this word to be taken like gospel. In fact in a team of smart but less experienced engineers, there should be a good expectations of cross-questioning. A good senior leader will explain their thinking is very approachable ways and welcome questions. They will never try to harshly criticize the solution that someone else might have come up with. They are good about sharing feedback, but also good at making sure its delivered in a way that does not harm the one at the receiving end.

* Great communicator and bridge: Senior engineers can understand what is being said in-between the lines. They act as bridges that help move things forward, often between cross-functional teams (product <> engineering) or between separate engineering teams. They help move us past gridlock through their use of empathy and humility. They try to reason from first principles and use their strong technical acumen to ask the right questions, rather then try and come up with answers all the time. Asking the right question is often more important than trying to come up with the right answer.

* Value quality, performance, security and maintainability: Senior engineers understand that software is mostly written for other humans to read, rather than for machines to compile. Therefore maintainability is of primary concern. They set a high bar for quality and performance. They know that valuing users privacy and keeping their data secure is also a primary concern of the engineering team.

* Have fun: Senior engineers are pretty serious about their responsibilities, but also learn to take themselves not super seriously. They have fun along the way, and make the most of their relationships, at work or outside.

How to Spot and Magnify the Powers of Your Engineering Superheroes, an interview with Lloyd Tabb

Tabb is the founder and CTO of Looker. In this interview Tabb highlights the four superpowers which a team must have and talks about how to best recognize and channel their powers. Also, he describes the profile of the engineering leader, who must corral but not constrain these heroes. Tabb’s take on star programmers and dev team dynamics will inform how you'll work with your team and be able to identify your own strengths. If you think you don’t fit into any of these profiles, please reply to this email and let me know what your superpower profile is like. I would be very curious to know.

Persisting as a solo founder by Vishnu Mohandas

Vishnu gave up a cushy job at Google to build a privacy friendly photos app. He talks about how hard it has been to work as a solo founder and what changes he has had to make to survive in this new pandemic world reality. Though many of us are not entrepreneurs, Vishnu’s lessons are valuable for anyone since we are all working on a startup of you! Some things that I liked from his post:

* Patience: Vishnu talks about how meditation helped him deal with negative situations. He talks about how he will take a pause and “sit out” a situation that would otherwise overwhelm him. We don’t talk about this often. On a weekly basis I have found multiple things that have the power to escalate and cause me mental / physical harm. The best thing we can do is remain calm, take a pause and see if we can walk away from that situation temporarily and come back with more resolve later. It takes a lot of patience to do so.

* Reducing distractions: Vishnu disabled notifications on his phone, and also works in a “tree of checkpoints”. This is a great insight. Also, have you heard of The Eisenhower Matrix?

*

First principles thinking allows us to seek the truth and think more objectively. James Clear says that a first principle is a basic assumption that cannot be deduced any further. Rene Descartes, the French philosopher and scientist, embraced this approach with a method now called Cartesian Doubt in which he would “systematically doubt everything he could possibly doubt until he was left with what he saw as purely indubitable truths.” One way to get to the root of the matter, is to use the 5 Whys technique. Its an iterative way to reach to the bottom of a situation. Until you determine the root cause, keep repeating the question "Why". Each answer forms the basis of the next question.

Any situation, in personal life or at work, has two stories behind it. One is a story from your perspective. Another story is from the perspective of the other party involved. But there's a third story. That's the story from the perspective of someone who is an independent third party observer. When you are one of the parties keenly interested in the outcome of a situation you can tend to lack objectivity. But when thinking about the same situation from the lens of a third party observer will give you much more objectivity.

In conclusion, in order to get better at decision making we need to get better at thinking objectively. It can be hard, but three tools are useful when doing so. Thinking from first principles, using 5-whys technique, and finally third story. A good book to read more about this Super Thinking.