Writing a technical proposal
Writing a technical proposal is something I’ve seen more than one person struggle with, sometimes fighting to convince others of something they believe in, and other times not knowing how or where to propose new initiatives. There is usually not much documentation on how to do them, and, likely, your company doesn’t have an established way of doing it either. To make matters worse, there is no one-size-fits-all approach, no standard way of doing it. Actually, it varies greatly from company to company, and even within the same company. For example, it’s common in large companies to have two proposals, one for the technical committee (CTO, architecture committee, technical leads committee, etc.) and another to present to the management (CEO, CPO, board, etc.).
In this newsletter, I’m going to try to cover how to prepare a technical proposal to increase your chances of success, taking into account things like the audience, stakeholders, or organizational buy-in. This text has been in my head for years because, as mentioned above, I’ve seen many proposals and efforts fail due to very common mistakes, from not covering something as basic as why it’s relevant to the business to presenting it poorly to key stakeholders, generating distrust in the initiative. And one interesting thing is that after going through many companies, I’ve never seen any organization teach you how to do it; it’s something you learn “on the job.”
A technical proposal is not just a document where you do a “brain dump” of your ideas and solutions to a problem. It’s a means to communicate to others why a problem is important, the analysis you’ve done to solve it, and the solution you propose after weighing everything up.
The newsletter has become too long, so I won’t cover the approval process, committees, and the like in detail. That is, who and where to present them.
What do I mean when I talk about technical proposals?
I’m referring to substantial proposals, that is, technical proposals that often require a cross-cutting change that can affect the entire company. For example, a change in architecture, technology, tools, etc. I’m not referring to proposals that stay within the team and have no impact beyond it.
In most companies, when you want to carry out a technically significant initiative, it requires the approval of certain stakeholders. These stakeholders depend a lot on the organization; it could be the CTO, it could be an architecture committee.
Why, Purpose
One of the problems I’ve encountered with many proposals is that they forget to mention why what they propose is necessary, what the motivation is, and above all, how it is tied to the business. How does it benefit customers? How does this affect the company? What you propose makes sense, but is it necessary? If you have evidence of the need, incorporate it as well. For example, if you’re trying to solve a scalability problem, add a list of all the incidents caused, all the related bugs, etc.
Many proposals only talk about technology, how good it is, its virtues, but they forget to mention why that benefits the company. And I’m not just talking about proposals with a direct impact on money; I’m also talking about more purely technical proposals, for example, improving the developer experience (like improving CI). Just because a proposal is correct or brings certain improvements does not mean it’s good for the company at this moment.
We may be improving a part of the system, but that may not be the biggest pain or need we have right now. In other words, simply changing from Python to Go to improve system performance is not enough if it’s not related to a business benefit; the investment is not worthwhile. Or why change a Python component to Go to gain a 1.1x improvement if the problem limiting the system is how we scale the database, and solving that would lead to a 10X improvement…
We must consider the “opportunity cost.” The organization’s resources are limited, and when you do something, you are giving up doing something else. Is there something else that adds more value than migrating to Go? What are we not doing by doing this? For example, we can propose an initiative to reduce technical debt by demonstrating that it will reduce KTLO, and with that, we will be able to deliver faster.
This leads me to mention something that many software engineers lose sight of, “momentum”; knowing when to present a proposal is as important as the initiative itself. It’s important to understand the current situation of the company, the system, and your area if the company is very large. Also, know how to take advantage of situations like crises to present certain improvements.
For example, if we’re in dire straits because the system doesn’t scale horizontally, it’s not the best time to start an initiative to make CI 20% faster. On the contrary, if we’ve just had an incident and it took an hour to put the fix into production due to CI, it’s a good time to launch that initiative.
Finally, if you want to propose a change, you must become an expert in the current system. It’s very difficult to come up with a solution if you don’t know the problem well.
Buy-in and Stakeholders
Another major mistake mentioned earlier is presenting poorly worked proposals. This means, before presenting the proposal to those who have to approve it, make sure it’s complete, that it covers everything they expect to see (more on this in the technical document section).
Avoid ambiguous language, and adjectives like “falls a bit short,” “substantially improves it,” and “we believe that,” the proposal must be precise and incorporate data, and metrics that support our claims. It’s very useful, whenever possible, to include a prototype.
The best thing you can do is ask for a lot of feedback from peers, and seek advice/mentoring from other technical leaders in the organization. For example, if you’re on a team and you have a proposal to change something that affects the entire company, make sure your team has reviewed and provided feedback on your proposal. As a general rule, if everything is okay, ask again; no one makes a proposal perfectly the first time.
Also, if your company has figures like architects, principals, or the like, ask one of them to help you with the proposal. This is simple but important; not only will the proposal be more polished, but you’ll also have an ally, a sponsor who will support you when the organization has to make the decision. If you don’t have these types of figures in your company, think about who in your organization has the technical knowledge to provide valid and critical feedback.
In addition to technical feedback, it’s essential to seek feedback related to the business. To do that, understand who your key stakeholders are. Just like before, this is not only important because they will give you feedback on whether your proposal answers their questions, but also because you will gain support. And this is something that deserves special mention: the famous buy-in. When you’re going to present a proposal that is cross-cutting and can have a significant impact on the organization, having allies is crucial for it to succeed. These are the people who will endorse you and lend their support when the decision is made. So, it’s important to identify who they are and involve those you can. Don’t interpret this as “send them the proposal as soon as possible”; quite the opposite. What I’m talking about is that you have to start conversations
with them and start hammering away at the problem you want to solve and why it’s important. Remember, it’s much more important that people leave with the feeling that there’s a problem to solve than how beautiful your solution is.
I’ll tell you something that happened to me a few years ago when I worked at Google. My team (Spacejam) had to make technical proposals to modify the Android framework, but we were not part of the framework, so we needed their approval for everything. During the first few months, we found it incredibly challenging to make progress on any initiative, to the point of having one blocked for an entire month. Talking to my manager, he proposed a very simple solution, “let’s go to San Francisco.” So, a few weeks later, there we were, with the sole purpose of having coffee with the key people, and you know what? It worked.
Smells
Finally, before getting to the document itself, some smells make everyone raise an eyebrow and question the proposal a lot. Things like changing an entire system that is in production and working, doing a massive refactor, and Big Bang rewrites.
Very large proposals like rewriting something entirely tend to scare people because of the risk they entail. It’s much easier to approve a proposal where the risk is much lower. So, if you can propose a phased approach where the benefit begins to be seen in the early stages and then iterates, it will be easier to approve.
Even if you can, it’s a good idea to divide the technical proposal into several parts and attack each one separately at different times.
The same goes for initiatives that show a lack of analysis (a typical example is focusing on the request average instead of looking at percentiles), a lack of knowledge of the system, etc.
Try to be as explicit as possible with the different alternatives and their pros and cons. If we don’t do this, it’s most likely that people will ask for that analysis, and have debates about whether it could be solved this way or that way when it’s actually something you’ve already analyzed, so it’s better to be explicit.
It’s important to make clear what the objectives are and what they are not. This helps avoid fruitless debates and keeps the conversation focused.
Once you share the document with people, keep it alive, i.e., respond to the feedback they give you, either to discard it or to change the document, but don’t leave the comments hanging. That makes the document very difficult to read and follow. If you make decisions, reflect them in the document, and if you conduct tests, do the same.
Technical Document
The technical document varies greatly depending on the company and even the department. For example, when I worked at Google Android, the technical document had some mandatory sections for legal issues, such as the logs that were going to be added or how the Android system would be affected by this new feature (e.g., memory, disk, etc.). But there are many different formats like RFDs or ARDs; you can see more examples and the companies that follow them here.
A very good and well-documented example, as they usually do, is Gitlab. Not only do they have the technical document, but also how they use it and examples.
Let me finish with an example of a Technical document:
Technical proposal title
Purpose
The purpose describes what the service or feature does. Why is this relevant for the business?
Try to keep this to one sentence.
Background and context
Why do we need this feature? What problem are you trying to solve? What is the context for another team member reading this document?
Requirements
What are the outcomes this service or feature must exhibit? These could be metrics like response time or characteristics of a component built on the frontend (e.g. responsive to various mobile device sizes). You can include user stories here to describe the requirements.
- Goals
- Non-Goals
Solutions
This is the longest part of the design doc and requires the most research, planning, and preparation. This is your engineering approach to solving the technical problem.
It can include pseudocode, database schemas, flow diagrams, wireframes, components, input validation, security considerations, API endpoints, sample API requests/responses, and countless other things.
You should also mention alternative approaches to solving the problem and the tradeoffs. Example:
Option 1
- Pros
- Cons
Option 2
- Pros
- Cons
Implementation plan / Phases
There might be some overlap between the detailed design and the implementation plan, but this section includes the actionable items (i.e. epics and tasks) required to complete and ship the service/feature.
Tests
What tests will you write? How will you ensure this service/feature works? How will you know when this service/feature stops working? Which tests would guarantee that the system/feature implements the expected behaviour?
Monitoring, Alerts & Runbooks
How do you launch this service/feature? How does someone else troubleshoot it?
Which metrics would display that the system/feature is working as expected? How will you monitor it?
