Our Software Development Manifesto
We have been working on our own software development manifesto for some time now as the Engineering team. It was a very useful process for us to define our role within the company, our software development culture and how to scale our team. Since our manifesto is the basis of our software development process, it has also helped us a lot in creating a new team structure and specifying roles in product teams (which is the topic of another article).
We wanted to share our manifesto, why we needed it and what stages we went through, to help others to create their own manifesto.
In the last five years, Armut has grown its business by about 1000%. We are the market leader in Turkey, as well as, Romania and Egypt with the HomeRun brand.
Our Product Team has grown by 100% within a year
With the growth of the company, we started to hire more developers, product managers, and designers to our product team. They all had different backgrounds and experience levels. Because of the fact that so many people have joined us in a short period of time (and the fact that we will continue to hire new people), we started to worry about how to introduce our software development culture to newcomers. In all companies, as the company begins to grow, one way or another, company culture begins to form. But for the start-ups that solve the problems of customers with technology, it is crucial that the software development culture evolves in a healthy way.
We started investigating how other companies approach this issue. And I came across an article about how LinkedIn’s VP of Engineering Kevin Scott structured engineering teams at LinkedIn and AdMob. Along with other very useful tips and advice, one of the things that caught my attention was what he said about the cultural manifesto.
Create your own Cultural Manifesto
The single most valuable management tool while you’re scaling your engineering team is something I call a cultural manifesto. This is a document or a set of materials to help your entire engineering team get on the same page about how you make and operate things, and how you function as a team. — Kevin Scott
Kevin’s article was very inspiring. Also, during our search, we came across a variety of manifestos written by other companies too (see references below) and we benefit from them to create our own.
First of all, you don’t have to hurry while writing your own manifesto, it took a month to create our first draft, and then we worked on it for another month to finalize it. So take your time, involve many people as you can at every stage, get their opinion, benefit from their experience. Don’t feel intimidated. After all, it is something you familiar with already, it is your culture. You just need to compose your existing culture into a written set of principles. When the team no longer considers the manifesto does not fit its own reality, it can be reviewed and changed again.
The best method to follow when creating your own manifesto will be collective thinking. We did a series of meetings and discussions. We included all our developers in this process, regardless of their experience or their background. As a result, we have created a manifesto that reflecting on our software development culture.
I hope that our manifesto will help you in creating your own.
Armut Software Development Manifesto
Software innovation, like almost every other kind of innovation, requires the ability to collaborate and share ideas with other people, and to sit down and talk with customers and get their feedback and understand their needs. — Bill Gates
Why we need a Software Development Manifesto?
As software developers, our goal is to develop products that solve customer’s problems, in order to drive growth. The purpose of this manifesto is to describe the methods we apply to achieve and succeed in our goals, which are the methodologies we use, how we function as a team, and consequently to define our software development culture. The culture of a team is one of the major factors influencing how enjoyable work is, it is vital that as we grow we nurture and retain a supportive, collaborative and enjoyable team culture.
Another purpose is to define a contract between software developers and stakeholders by defining and standardizing how we do things and how we operate things.
The Fundamental Principles
The Only Constant Is Change
Like every other culture, the software development culture is a living organism that needs to grow, adapt and change to survive. Every three months, we will review our manifesto and make changes if it’s necessary.
We are all Product Developers, not just Software Developers
The distinction is important, we must all contribute to the definition of features and direction of the product. If we have empathy for our users we will create better products, everything we do should be aligned with the strategic goals for our products and company.
“Why”, “how” and then “what”
We engineers will take a step back from “what” and focus on “why” and “how” first before “what” as it leads to better solutions. We will understand the problem well, start with the customer and then come up with a solution. When it comes to “what”, we will use a decision matrix to pick a strategy, solution or technology.
Why=The purpose: To ensure that we are able to keep doing what we are doing.
How=The process: Our values, the behaviors, beliefs, and principles that guide our decision-making.
What=The result: Our product. The need that we meet, the problem that we solve, the way we solve it.
We actively encourage learning and development.
We want to build and maintain a team that enjoys learning new things, this growth mindset must be a key trait of team members. Learning new technologies and techniques increases our value to the team and improves the products we build as well, it also motivates team members and helps to drive innovation.
Own
We own the products we build, we adopt the technologies we use and the mistakes we made.
Have fun together
Treat your teammates as professional friends. Trust each other. Don’t take things too seriously!
How we create, build and make things?
Coding Standards
We have to write code for humans, not machines. Try to keep methods as short as possible, classes with a single responsibility, few parameters, avoid redundant comments, etc.
Every team follows the guidelines and best practices of their preferred programming languages to conform to the maintainability and stability of the code. Guidelines we created can either apply platform-specific standards or customized but inherit community standards.
As Robert Martin says: “leave the code better than you found it.” Make things smarter, faster and better!
Code Reviews
No single line of code can be deployed without an approved pull request, even when targeting the test environment. We should look over the code and consider questions below:
- Are there any obvious logic errors in the code?
- Looking at the requirements, are all cases entirely implemented?
- Are the new automated tests sufficient for the new code? Do existing automated tests need to be rewritten to account for changes in the code?
- Does the new code conform to existing style guidelines?
Stack
We accomplish our goals by developing products independent from programming languages, tools, and platforms. Depending on resources, requirements, and necessity, we adopt new technologies. For each new technology consider whether the team can take the cognitive load. For each new technology consider if it is really necessary.
Architecture
The primary purpose of architecture is to support the life cycle of the system. Good architecture makes the system easy to understand, easy to develop, easy to maintain, and easy to deploy. The ultimate goal is to minimize the lifetime cost of the system and to maximize programmer productivity. — Robert C. Martin
There are no architects in our teams, there are however variations in depth and breadth of experience.
When designing our architecture, we consider not only the needs of the present time but also the needs of the future. We design our architecture as a team, taking into account modern and proven best-practices and approaches.
Build vs Buy vs Open-Source
Depending on requirements and considering quality and cost, we buy or develop the related services or components.
- Favor building over using batteries included frameworks and libraries.
- Build when there are no alternatives or the alternatives are too expensive or complex.
- Open Source libraries should be used when possible, just ensure that the project will have longevity i.e. backed by an organization.
- Buy when then the Total Cost of Ownership (TCO) is lower than building (including initial development and maintenance)
Building and Deployment Pipeline
Continuous integration and delivery is the key to maintain high-quality code and fast feature deployments. We apply the standards for all of the projects attached to the building and deployment pipeline.
Launching Features
Develop, build, test, deploy, monitor, repeat.
Scaling Patterns
We will build distributable, scalable and highly available services. We will create solutions today which caters to 10x the current scale to ensure business continuity and avoid setbacks. This is an important guiding variable for the prioritization of work.
Testing
A definition-of-done is required to create products consist of modules and services. Each of them is developed independently testable, which enables the CI/CD pipeline to quickly run the high coverage unit tests autonomously.
We will clearly document the approach for how we test everything. For every feature we build, we will write unit, integration, functional, end-to-end and performance testing. Testing is an integral part of the definition-of-done.
Security and Data Privacy
Our principles enforce environment isolation and separate policies for security and data privacy concerns. We will embrace the principle of least privilege (PoLP) whenever it’s possible.
API Documentation
API defines communication standards either between services and client-side applications or between the inter-services. We provide required contracts to generate relevant documentation for APIs.
Don’t sacrifice quality
Modernizing, refactoring, code reviews, tests, integrated pipelines, and monitoring are the main principles to maintain and improve code quality that directly affects the product’s stability, extensibility, performance, and even a future roadmap. Sacrifice on quality accumulates technical debts that will become noticeable issues to end-users. More technical debts will block further feature developments or enhancements without reconstruction.
KISS (Keep it Simple, Stupid)
Simplicity is the ultimate sophistication. Look for perfection, but not yet. Iteration is that friend that gives you the right advice at the right time. First, do it, then do it right, then do it better. Any sufficiently complex system cannot be built out of design, it has to be evolved. Above all else, complexity is hard to debug.
Divide & Conquer
DRY (Don’t Repeat Yourself), A basic principle of software development aimed at reducing repetition of information. Every piece of knowledge or logic must have a single, unambiguous representation within a system. Divide your system into pieces. Divide your code and logic into smaller reusable units and use that code by calling it where you want. Don’t write lengthy methods, but divide logic and try to use the existing piece in your method.
Automatization
Automate code analysis, building, testing, deployment, and every other possible task.
Measure and Report
We assess all the needed and applicable factors. We demonstrate the shift on the dashboards with the graphics and generate reports. Measurements form the basis of our quality improvement and incident management.
How we operate things?
Monitoring and Alerting
Specific instruments having configured alert settings based on preconfigured or dynamically calculated values monitor our apps and services. An alert produced from monitoring systems always leads to a single actionable incident that solutions and causes are documented.
Find Issues Before the Client
Before it is delivered to production, we need a strong test strategy to ensure product quality. Ensuring new features are ready to be released relies on a comprehensive requirement specification and definition-of-done list.
Resource Management
We embrace Infrastructure-as-Code perspective to provide scalable, consistent, high available and manageable resources for our services.
Least Privilege Access
Access to production is limited with permission policies applied across resources and services.
Decommissioning & Depreciation
When adopting a new technology or re-structuring a service or module; we determine versioning, backward compatibility, and transition steps into the future roadmap we created.
Feedback and Report
We measure and persist in specific metrics that drive the required information to reports. We can provide periodic and automatized information via integrations or instantly visualized dashboards.
