Let's cover a tactical way to improve your output and attain more certainty that your approach will work. The simple idea is about writing down your thoughts on what problem you are solving and how you are going to approach it, circulate it within your team and get inputs / buy-in from teammates.

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.

This is a public episode. If you would like to discuss this with other subscribers or get access to bonus episodes, visit swecareer.substack.com