Repository navigation
Tech Standards
Autonomy is great - it's what enables squads and tribes to innovate. However, when squads work in isolation they can't benefit from each other's experience and lose a valuable opportunity to learn. Furthermore, our code will lack consistency, increasing the learning curve when services or engineers move between squads. Consistency also helps keep our CI/CD pipelines and use of shared infrastructure simple. We therefore need to find a balance between autonomy and consistency.
This is where tech standards come in. By having opening up discussions around standards, we leverage the first hand experience of our engineering team, and provide a learning opportunity for everyone. By capturing the discussion, we can challenge the status quo when new technology becomes viable or when our context changes. We can also reduce the risk of moving to a new technology which does not satisfy the key selection criteria previously identified.
We need to protect our autonomy, so should only standardise when it is worthwhile to do so. An example would be selecting a general purpose message broker. There are several candidates (RabbitMQ, ActiveMQ, SNS/SQS, Kafka* and EventBridge to name but a few). Adopting multiple brokers would significantly increase our infrastructure complexity, incur a learning curve and would limit the interoperability of our services. Hence standardising on a general purpose message broker is worthwhile.
Other factors to consider when deciding to standardise is how painful a decision is to undo. Signing up to a commercial license, or re-writing multiple services is likely to be expensive, time consuming and complex, hence taking the time to formulate and agree a standard is likely to be worthwhile. In contrast, swapping out one unit testing library for another can be done on a service by service basis, as time allows, with little or no co-ordination between squads and repositories. The learning curve required to move from one unit testing framework to another is typically small too. Hence standardising on a unit testing library is less worthwhile, although still potentially beneficial since not all unit testing libraries are created equal.
*Kafka is not actually a general purpose message broker, but is frequently confused for one.
- Search for an existing tech standard
- Sanity check your proposal with a respected team member
- Create an issue in this repository
- Invite discussion from anyone you know has interest or experience
As the author of the tech standard, you are responsible for driving it. Standards which have not been agreed and lack activity may be closed.
In practice there tends to be two types of discussion
- Standardise on X?
- e.g. Standardise on a Node.js unit testing library
- What is best practice for Y?
- e.g. What is the best practice for logging?
The former tends to lead to a more concise debate and outcome, the latter for an open ended, but still valuable discussion. Either way, a good tech standard will have the following sections...
First of all, a good tech standard will have a neutral title, e.g. "Standardise on a Node.js unit testing library", rather than "Standardise on Pino for unit testing"
A good tech standard will lead with a clear problem statement, which includes a description of the author's context.
Next, a good tech standard will present an initial set of candidate solutions, which may evolve as the standard is discussed. The list may also include common solutions the author does not believe are appropriate, and the reasons why.
In addition, a good tech standard will propose an initial set of key decision criteria. As with the set of candidate solutions, these may evolve as the standard is discussed, and include a set of common decision criteria which the author believes are not important for this context.
A good tech standard will objectively evaluate the potential candidates against the decision criteria.
Finally, a good tech standard will have a conclusion summarising the discussion and stating the outcome, and how it will be delivered. Good intentions are not enough, a tech standard needs a good mechanism to be successful. A mechanism is only good if it is the path of least resistance.
Common mistakes are:
- Not making the effort to write a good standard
- Writing a problem statement that is too broad (will never reach agreement)
- Writing a problem statement that is too narrow (nobody else will care)
- Using logical fallacies to justify a solution
- Evaluating solutions in relation to another organisation's context
Anyone. Watch this repository and join in the discussions.
Ideally the decision process will be collaborative between engineers of all experience levels, however from time to time we may need to pull rank (sorry).
Sometimes we cannot agree on a standard. This is OK. If possible the standard should at least limit the number of potential solutions, excluding those which were found inappropriate, and providing guidance on when one acceptable solution might be preferable to another.
You can tell the status of a tech standard from the GitHub label
| Label | Meaning |
|---|---|
| Proposed | The standard has been proposed and is under consideration |
| Adopted | The proposed standard was adopted. Engineers are expected to adhere to it in future and may need to migrate existing code |
| Rejected | We have made a conscious decision not to standardise |
| Deprecated | A previously adopted standard has been deprecated. It may be superseded by newer standard |