Solid architecture is the product of a culture that values holistically and thoughtfully designed systems. This document identifies the driving questions necessary for Vox Media engineering teams to produce well architected systems.
The following questions will encourage high quality, long lasting and maintainable code. Good system design has thoughtful goals, good architecture enables these goals.
Designing for Completeness
Writing software at Vox Media requires more than just making something work, it requires thoughtful attention to the goals of the business and supporting product. It encourages a mindfulness on the following topics.
- Business – How does it fit into the business goal?
- Users – Who will benefit from this system? How has this been validated?
- Maintenance – Who will maintain it? How will they understand the design? How will they have confidence their code will work? What parts of this system are worth documenting?
- Performance – how many users, connections and requests will it serve? Where are the performance boundaries of this architecture?
- Security – What considerations have been made to secure data, costs, and processing time?
- Extensibility & Future – What is the future of this product? How will new features be added? How will this be used in other systems?
- Delivery Pace – What concessions have been made to ship this quickly?
- Consideration for what it is not – How have you clarified what this is not built to handle?
Designing for Others
Our goal is to build systems in service for others. This mindset encourages a thoughtfulness for future users and maintainers. How does your design empathetically serve others?
- Clarity – How easy is it for everyone on the team to understand? How will they be aware of how the design considerations (from above) shaped the current architecture? How can you explain this approach in a sentence or two?
-
Inclusion and Reuse – How have you encouraged others to use this module with confidence?
- +1 Contributors – How can the next person contribute to this work? How will they confidently deploy their changes?
- Communication – How have you explained this approach in diagrams, slides and other non-code concise documents?
- Testability – Can others confidently make contributions to this code?
- Confidence – How has this design reduced classes of common bugs, performance corners, confusion and user support?
- Creator Independence – How have you ensured you won’t be bugged in slack, email and phone for the next 3 years about this code?
- Soliciting Feedback and Review – How have you identified interested parties, shared this design, welcomed feedback and responded?
- Friction Reduction – How has this design reduced the work required to take other people’s ideas to shipping code? How has this multiplied the ability of the entire team?
- Mitigate Potential Harm – How does this system prevent a bad actor using this feature and/or data for potential harm?
Site design and styles heavily influenced by our Code of Conduct. Images courtesy of Alesha Randolph.
This document is released under the Apache 2.0 license.
