The power of proposals ✍️
Or, how to get paid to write good
👋 Hello!
Welcome to the very first edition of High Growth Engineering — I’m super excited to share this with you.
Before we start, a quick refresher on why I’m doing this. The goal of this newsletter is to discuss techniques for building better software and being more effective in high growth companies. I mix in longer form content — think a short blog post that you could read in 5 minutes — with some of my favourite links.
If you subscribe, you’ll receive weekly posts from me on topics such as:
Techniques for testing in production
Estimating the payoff of work
How to tame Slack 😿
Writing maintainable software under time constraints
Project management and prioritisation as an engineer
Amongst many more topics. That said — on with the show!
The power of proposals
This section is adapted from an original post on my blog: A product & engineering proposal template
You’ll hear a common refrain from me on this newsletter. Spending time improving the clarity and quality of your written communication is one of the most impactful activities you can do as a software engineer.
Want to know an easy way to get paid to practice writing? Write proposals at work.
What are proposals?
Documents that you write as part of the process of doing work, such as building a new feature. At the highest level, they define a problem, and how you propose to solve it.
You might also hear them referred to as RFCs. I prefer the word proposal as the acronym tends to exclude non-technical folks for no good reason.
Why write them?
They're useful for a few different reasons:
Writing your thoughts down is a forcing function for clear thinking. You can’t convince others if you don’t understand the idea yourself.
They amplify the underlying strength of the idea. I’ve never seen a good idea that didn’t get get stronger after writing a proposal. Weak ideas become self-evident after you’re forced to explain them to others.
They allow other people to give feedback to you or your team before you build anything. External feedback helps surface unknown unknowns, and can provide context you don’t have.
They are point-in-time documentation of a system. This is usually better than the default of no documentation in fast growing technology companies.
When should I write a proposal?
A common complaint when asking people is: “writing proposals takes too much time. It’ll slow me down from writing code.” To that I say, weeks of coding can save you hours of planning.
Write proposals for every non-trivial piece of creative work. A rule of thumb is that I wouldn’t write a proposal if completing the task would take less than the time it would take you to write a proposal for the work.
Who should write proposals?
Most commonly, product and engineering teams building software. But in principle, any team undertaking projects.
Writing better proposals
OK, that’s all quite theoretical. At this point, you might be convinced that proposals are good. But, what can you do to write better ones?
Use a proposal template
If you do one thing from this newsletter, do this.
Proposal templates provide a standard structure to a document before the writer fills it out, without being as prescriptive as filling out a form. Using a template has many benefits:
The writer receives helpful prompts on areas they might not have considered — how does the service fail? How are we going to measure the success of this? This occurs at exactly the time when they should be thinking about these things.
Readers can scan similar documents more easily. If particular areas seem light on the ground, they can easily jump to them.
But where can I find a proposal template Stephen?, I hear you cry. Don’t worry. To make life easy for you, I’ve attached the proposal template that I’ve used at Ravelin and Monzo. Feel free to use it for whatever you like: my only ask is that you let me know how you get on with it. Click the button below to see it on GitHub.
Sprinkle diagrams liberally 🗺
In software, a picture says a thousand words. Sprinkle your diagrams with sketches of architectures and flow charts of request lifecycles.
Write with confidence
Take a stand. Be clear to the reader what your plan is to do, absent any feedback that you receive.
Use subheadings for summarising main points
Subheadings are great at drawing the reader’s attention, and providing structure to the document. Take a leaf out of my book: in this section, you get an idea of what to do just by reading the subheadings.
Call out tradeoffs
All non-trivial software has tradeoffs. Some common ones are listed below:
Scale: how much load will this design support?
Extensibility: how easily can we extend the software?
Speed: how quickly do we need to build this?
Lifetime: how long will this software live?
Be clear when a tradeoff exists, and which option you chose. Justify why you chose that. There is no correct answer to the above — only good judgement.
Highlight areas for specific focus 👀
In any proposal, there will be sections you’re confident in, and sections you’d like more eyes on. A quick trick to get the useful feedback you need is to specifically call these areas both at the top of the document, and near the specific areas. Something like the following works well:
We’re confident about the data structures and abstractions mentioned. However, we’re less up to speed on the failure modes of etcd, and how that impacts correctness of this service. We’d love specific feedback on how to make the design more resilient to failure.
The best of the internet 🔗
Every week, I collate some of my favourite links to share. Found something cool, or built something great? Send it to me by replying to this email and I might include it in the next edition. 📧
Janessa Lantz: How to coach new writers ✍️
In this article, Janessa gives great advice on structuring documents, and editing them to show their true potential.
Jeff Dean: Achieving Rapid Response Times in Large Online Services
This isn’t related to the rest of the post. But, it’s one of my favourite technical videos of all time, so I had to share.
In this video, Jeff discusses techniques that they use to reduce tail latency at Google. Tail latency describes the slowest experience that your service provides. Some highlights:
16:17 - Sending backup requests — a copy of the same request to a different server — if you haven’t received a response in a certain amount of time.
24:33 - Implementing the techniques discussed means that you can run Terasort on your cluster, and get the same response times if you hadn’t implemented them. 🤯
Gergely Orosz: The Product-Minded Software Engineer 📱
This blog post analyses a type of software engineer that cares deeply about the product they are building. In my personal experience, these engineers tend to be the most successful at high growth companies: it’s difficult to go far if you don’t care about the product.
Thorsten Ball: What you think is bad about remote work, can, well, actually be good
Thorsten discusses that the often perceived downsides of remote work can actually be advantages on certain dimensions. I empathise heavily with this. Personally, I feel my in person presentation skills are lacking. I get nervous, and I find it hard to speak off the cuff. I’m far more confident collecting my thoughts, and communicating them through prose. Remote work creates ‘a different playing field’: not objectively better or worse — just different.
That’s all from this week’s High Growth Engineering! If you enjoyed it, I’d really appreciate it if you could do one of the following:
Let me know — positive feedback is good!
Share it with a friend that would find it useful
What problems did you run into today? What would have helped you? I’d love to know to inform what to write about in future. Just hit reply on this email.
Speak soon,
Stephen