Table of contents
Blogs· 4min June 28, 2023
Andy recently wrote about what he considers to be the key ingredients for bootstrapping a new engineering organisation. Many of these ingredients are about what you use to build your organisation with. However, this post describes one key element of how you do it. This blog post describes one way of making decisions and designing new changes which scales well with a growing team, and includes everyone in the process.
In some senses, the way you make decisions in a small engineering organisation may seem unimportant. Especially when there is a small team involved, decisions can be made synchronously via conversation. Similarly, system design can be conducted at a whiteboard; be it physical or virtual.
However, as an engineering organisation grows, face-to-face decision making and design starts to scale less well for a couple of reasons:
If you don't start off making decisions and designing new things in a way that scales well with the size of your engineering organisation, you end up with a "blind spot" where no-one really knows why things were done the way they were when your organisation was started. Of course, this isn't strictly speaking true; much of this initial knowledge might become "tribal"--known by everyone--without the need for any specific practices. However, sooner or later you'll need something better than "face-to-face".
As an engineering organisation grows, synchronous decision-making in conversation becomes harder to scale, and becomes less inclusive. In my view, the solution to this problem is to start off by making decisions via the medium of writing, rather than talking.
In the beginning, in a small team, it might be very natural for decisions to be made verbally; and that's fine. However, in order for the decision-making and design to be preserved for future team mates, and for it to be easily consumed by the masses of your future organisation, I still think it needs to be written down.
A popular pattern for this is the Architecture Design Record (ADR), in which a short document is written to capture the context, outcome, and consequences of a decision. Provided an ADR is the artefact of the decision-making or design process, then you can rest assured that the decisions made as your engineering organisation was bootstrapped will be easy to share with new colleagues in the future.
This is probably true at any stage in the growth of an engineering organisation, but especially as it begins to grow beyond the founding members it is important to focus on problems before solutions. As with the early decisions, I think it's helpful to do this in a written form, so that problems and their solutions can be shared with a large number of colleagues in a way that everyone has access to the decision-making material.
My preference is to structure this discourse via two document types:
When you start considering a topic that requires a decision, or a new feature that requires a design, the idea is that you start off by clearly describing the problem you're solving in a PRD. A PRD might consist of some background information, the motivation for solving the problem, and the problem description itself. If everyone agrees on the problem statement, then everyone is on the same page when it comes to considering possible solutions, and making a decision.
Having agreed on the problem you're solving, it's possible that you may want to discuss several competing solutions. An RFC provides a structured approach for you to refer to a specific problem, and outline a proposed solution. This is equally useful for making a decision about the way your organisation is run, as it is for deciding on the architecture for a new functional component in your system. An RFC might contain some background information, a reference to the problem, and the proposed solution.
Making decisions and designing changes via PRDs and RFCs has a number of advantages in my view:
I would advocate utilising PRDs and RFCs from the very beginning when bootstrapping an engineering organisation. Doing so builds a culture of writing to make decisions and design new systems, and makes your decision-making transparent and accessible from the beginning. Any decisions made outside of a PRD/RFC and be recorded in ADRs, so that they don't get lost in the mythical history of your organisation.
The end result is an iterative, cumulative history of all the decisions you have made in building your team and your product. The design documents describe the evolution of your system, and make ideal reference materials for new team members, or for future conversation. If anyone wants to know "how your system works", you can just give them a curated list of RFCs to read.
In my opinion, using writing to make decisions and design new things is a great way of generating high-quality, living documentation, as well as for democratising and scaling the decision-making process.
I think that using writing to make decisions from early on in the life of an engineering organisation is invaluable. Not only does it set you up for success as your organisation grows, but it also builds a high-quality history of design that will be valuable again and again as your team and product are built.
I've found a good pattern for structuring this written material to be the use of three distinct documents:
These documents could be in Google Docs, Markdown files in a Git repo, or issues in a Git forge. The main thing is that you establish practices for using them as the medium for your organisation's decision-making and design processes.
Andy Kuszyk is a Staff Engineer at Form3, based in Southampton. He's been working as a software engineer for 8 years with a variety of technologies, including .NET, Python and most recently Go. Check out more of his tech articles on his blog.
Blogs · 10 min
A subdomain takeover is a class of attack in which an adversary is able to serve unauthorized content from victim's domain name. It can be used for phishing, supply chain compromise, and other forms of attacks which rely on deception. You might've heard about CNAME based or NS based subdomain takeovers.
October 27, 2023
Blogs · 4 min
In this blogpost, David introduces us to the five W's of information gathering - Who? What? When? Where? Why? Answering the five Ws helps Incident Managers get a deeper understanding of the cause and impact of incidents, not just their remedy, leading to more robust solutions. Fixing the cause of an outage is only just the beginning and the five Ws pave the way for team collaboration during investigations.
July 26, 2023
Blogs · 4 min
Patrycja, Artur and Marcin are engineers at Form3 and some of our most accomplished speakers. They join us to discuss their motivations for taking up the challenge of becoming conference speakers, tell us how to find events to speak at and share their best advice for preparing engaging talks. They offer advice for new and experienced speakers alike.
July 19, 2023