Especially in bigger teams, establishing and maintaining a common standard for software development is important and challenging. At the same time, it’s crucial to involve the whole team in the creation of the standard to ensure its acceptance and high quality. In this post, I present our approach for this: The regular meeting “Tech Talk” and the team guide.

TL;DR

• The team continuously discusses and commits to their guidelines in a weekly meeting. We call this meeting “Tech Talk”.
• The agreements are concisely written in a team guide, which serves as a reference for later look-up.
• It’s important to involve the whole team in the process of discussion and decision making. In the end, it’s about the team’s guidelines so the team should define them.
• To create the guide, use the tools that developers like: a Git repository, Markdown files, and the dev’s favorite editor.

Our Story

About 1.5 years ago, our current team was founded by merging two existing teams. The challenge was that both teams worked differently. For instance, they preferred different libraries and databases, they followed different coding conventions and packaging structure, they had a different development process and different ways of performing code reviews.

How do we bring those different approaches together? How do we commit to a common way of working?

We felt, that we have to talk about these topics and to commit to rules as a team.

The solution was the following:

• First, we set up a weekly meeting called “Tech Talk”. In this meeting, we discuss and commit to a way we like to develop software.
• Second, we write down our decisions and commitments in a concise record that we call “Team Guide”.

The important aspect here is that the team set their guidelines. The decisions in the Tech Talk affect everyone so everyone should be involved in the decision-making. Every team member can have an impact which increases the motivation to participate and the acceptance of the guide. A contrary approach would be an ivory tower where only the senior developers gather together and decide on the way the whole team has to work. That would be very frustrating for the rest of the team and would lead to poor decisions.

The Weekly Meeting “Tech Talk”

In the weekly Tech Talk, we discuss topics like:

• Naming Conventions
• Package by Feature vs Package by Layer
• Preferred HTTP Library
• Integration Testing vs Unit Testing - When to use which approach?
• Code Review Process

Each meeting should end with a concrete decision and a commitment by the team. Moreover, it’s important to concisely write down the agreement. Therefore, it’s important to moderate the meeting and focus on having an applicable outcome and a record. This meeting is not about endless philosophical discussions and dreaming.

The Team Guide

The team guide is written during the Tech Talk and concisely points out the agreements. It can be treated as a reference for looking up things later. The guide is not a record of the discussions with all pros and cons but a short documentation of the outcome.

Ideally, the guide is written with the developer’s favorite tools. Devs like Markdown and Git and they like to use their well-known editors. No dev like editing Wiki/Confluence pages in the browser. So that’s our approach:

• Git repository.
• Markdown files.
• Devs can choose their favorite editor. For me, that’s VS Code.

To render the Markdown files in nice HTML you can go with different approaches:

• GitHub Pages
• GitLab Pages
• A simple web server that delivers the Markdown files + Docsify to render the Markdown files on the client-side.

This way, writing the team guide is fun.

Collecting Topics

We maintain a Wiki/Confluence page where every team member can drop possible topics for upcoming tech talks.

Voting for a Topic

The decision for the topic of the next talk is made via voting. To make the poll as easy as possible, we use our instant messenger for this. Most modern chat tools have a poll feature built-in. If not, you can go with an emoji voting:

The poll for the tech talk on Wednesday is done on Monday. This gives the colleague that dropped the idea a little bit of time for preparation if required.

Decision-Making

Most of the time, the team can find an agreement by exchanging arguments and convincing each other.

But what if there is still no consensus at the end of the discussion? In this case, you have at least two options:

• Majority voting
• The tech lead decides

I’m careful with exclusively deciding by majority vote. Majority votes work if - and only if - all participants a) are affected equally by the decision and b) have the same expertise to make a well-founded decision. Often, this is not the case in teams with different levels of expertise and different roles. In the worse case, a majority that is not affected by the decision can outvote a minority which then has to suffer from the decision.

Still, it’s important to gather all opinions during the discussions and to actively ask introverted developers for their opinion if they don’t dare to speak up. This doesn’t mean that the final decision has to be made by a vote.

Alternatively, the tech lead can have the last word when it comes to hotly disputed topis. Often, they are accountable for the technical success of the team. Therefore, they can and sometimes should take the responsibility for the decision.

• Also, the tech lead should not set people up for votes that they know will fail. When a team votes down one’s work, consensus can be cruel. Instead, the tech lead should take the responsibility and deliver the bad news on their own.
• But mind that if the tech lead is deciding everything, it will quickly frustrate and demotivate the whole team as the team will feel that they don’t have any impact on important decisions.

Benefits

To wrap up, establishing tech talks and a team guide provides the following advantages:

• High acceptance due to team decisions. Every team member can participate and have an impact on the outcome of the tech talk. Therefore, the decisions made in the tech talk have a good level of acceptance.
• Establish development processes, standards, and a common structure for all services written by that team.
  • Standardization increases productivity.
  • It’s easier for everyone to understand each service and to become productive as they all follow the same structure.
  • A dev can now easier switch from one service to another one.
  • Especially in bigger teams (4+ devs), having a written development standard is important to ensure a common way of developing.
  • Having a written standard simplifies onboarding new team members.
  • Multiplying knowledge. Experienced developers can share their knowledge and influence the guide according to their lessons learned.
• More effective code reviews because tech talks allow you to focus on the business logic at hand.
  • Move the general discussion to the tech talk: “Oh, the naming for this type of classes should be discussed in the tech talk because it affects everyone”.
  • Refer to team decisions of past tech talks to avoid discussing the same issue again in the code review.