How to write effective docs around coding standards and code review with minimal guidance?

At a high level, there are a few ways for making a larger initiative go smoothly: 1. make sure all of your stakeholders are aligned before starting any work, 2. make sure there's a guiding principle or north star that all of your decisions are based on

1. Getting alignment

You'll want to "grease the wheels" by planting the seeds in your stakeholders' mind that coding standards at the company can be improved, and this can lead to increased developer productivity. At a practical level, this means just spending your time asking open ended questions to other developers about what they think about the code quality at the company. It can start very informally where you bring it up between meetings, at lunch, in the microkitchens, etc. This is a phase for collecting ideas but also just letting people know that there's going to be a initiative to improve code quality so they aren't taking by surprise.

I wouldn't even write a single doc yet until you've done the above. This is more of a user research step. This step is also useful for getting people excited about the upcoming work.

If you do notice there are patterns or trends around the feedback you are getting from users, I would start to write out docs for improving the initiative and open the doc for comments to the people that you spoke to. Include the feedback from the people that you talked to in the doc.

This should address the "war and peace" issue and really tease out what other people perceive low code quality to be.

1. Having a guiding principle

After you collect feedback from different stakeholders, you need to come up with a reason for why it's important to address all of this feedback.

• Is the initiative actually worth pursuing?
• What should the outcome be once the problem is solved?
• Can you quantify what the outcome looks like if the project is executed well?

An example of a guiding principle and action steps might be one of the following:

• Reduce the turnaround time it takes before a PR gets merged in
  • (example action: reduce the build time so users get quicker feedback about whether their PR is valid)
  • (example action: add a linter to reduce the number of repeated style conversations)
• Reduce the number of incidents that are caused in production from poor quality code
  • (example action: add a testing environment)
  • (example action: add more monitoring and observability tooling and set up alerts)

All of the actions in your plan should level up to the guiding principle that you think is the most important based on the feedback that you received from talking to other people.

First off, I totally get the vibe when leadership is being ambiguous with what they want (honestly, they probably don't entirely know themselves). But at the end of the day, it's much better to have the CTO with you rather than against you. I would try to build a bridge here:

• Assume good intent and that the CTO just wants their engineers to build stuff better while having you be a lead empowering these other engineers to be better
• Ask the CTO for any examples they can come up with where they felt like the code quality wasn't up-to-par and there was some sort of clear negative impact
• Try to talk to them in a friendly environment to extract this information as smoothly as possible. If you're in-person, the optimal one is over lunch or coffee

When it comes to the docs themselves, my advice is to essentially take what you do yourself with planning and code review, and just turn that into words as closely as you can. This is a great exercise for 2 reasons:

1. Building a deeper understanding of yourself is always valuable, particularly when you are trying to communicate your values and principles with someone
2. I don't know about you, but I love it when all the engineers I'm leading are on the exact same page when it comes to process, standards, and quality. This was a big reason why I was so successful at Instagram - I aggressively picked up mentees and molded them in my ways. My Instagram oncall case study is a great example of that: [Case Study] Revamping Oncall For 20 Instagram Engineers - Senior to Staff Project