In previous posts we described the reasons we decided to invest in Quality Standards in Transifex, as well as the fact that we made the Transifex Engineering Manifesto (TEM) public.

This post will go back to the time we started designing the process from which the TEM was born and is now maintained. We believe that the process is as important as the document itself, so prepare to see a detailed description of how we did things.

The Quality Standards Committee

Everything started when an engineer in our team decided to raise the issue of quality standards. He had a discussion with our Director of Engineering, who was very open to doing something about it in an official way. Up to that point, quality in Engineering was handled mainly by individual effort, which of course didn’t always work perfectly.

The outcome of that discussion was the formation of a team, which we called the Quality Standards Committee (QSC). Its purpose was to collect all existing guidelines, improve them, come up with new ones, and communicate them effectively to the Engineering team, so that they become our second nature when we create software.

We wanted this to be lead by a small group of people that would take ownership of this effort, orchestrate and facilitate it, review and filter input from other engineers and be able to debate the decisions of what makes it into the official guidelines.

Goals

The goals we set for the QSC were the following:

• Collect and document existing guidelines
• Seed “quality” in our engineering DNA
• Improve code quality (both new and old code)
• Reduce bugs & technical debt
• Create a better product
• Continuously adapt and improve
• Create a more respectful engineering environment

Writing the TEM

The first step we took as the Quality Standards team was to collect all existing material we had on the subject. We had guidelines and best practices scattered all around the place: wikis, Slack, email, even water cooler discussions. We tried to find all of them, organized them, refined them and put them in a Google doc. Then we took some time to write down a few new ones, based on our experience from everyday work and interactions.

The first version of the document was created a year ago, on December 2017.

Communicating the TEM

As soon as we started writing the document, our Director of Engineering told all engineers about this initiative. In the interests of transparency, we wanted everyone to feel included from the very beginning, as this is a very important aspect of the company’s culture. She also wanted to get engineers excited about what was coming, because the benefits everyone would get from this would be huge.

When the document was finished, we gathered all engineers and made a presentation. The 3 people of the Quality Standards team talked about the initiative, the purpose and goals of this new team, the Transifex Engineering Manifesto and what all of this meant for our everyday lives. We explained that we wanted everyone’s contribution in the form of suggestions, comments and feedback, so that we refine, improve and enrich the TEM over time.

Regarding its usage, we explained that this document was an agreement among all engineers and that everyone was expected to read it and start following it from the next day. Of course, such big changes cannot happen overnight, so we all understood that this would have a learning curve and that we’d all become better day by day.

By the way, the feedback we got from the team was amazing. There were a lot of suggestions, comments and questions, all of which allowed us to shape the TEM into something of great value.

Application

Creating a document with guidelines is one thing. Actually having people respect and follow these guidelines is a totally different story.

First of all, we made clear that it was everyone’s responsibility to -not only apply the TEM- but also push everyone else, in order to gradually improve the quality of our work. Like many other things in Transifex, this was about teamwork and respect.

Authors

Everything starts with the author; the person that writes a new piece of code or makes changes to an existing piece, is expected to follow all guidelines. But the place where most of the magic happens is code reviews.

Reviewers

All pull requests in Transifex are reviewed by at least one person, which is not the author. The reviewer has the authority to request changes from the author. Since the TEM was created, any request that is quality-related does not come from the reviewer; instead it comes from the TEM. This is very important, because it helps reduce friction between the person that is writing the code and the one that is reviewing it. So, reviewers are responsible for making sure that every piece of code that goes into our codebase adheres to our quality standards.

The same goes for the related processes. Authors need to write good commit messages and detailed pull requests, as well as follow the guidelines for code traceability. Reviewers need to make sure that this actually happens.

Retrospectives

Of course, sometimes things will not go exactly as planned. For these cases, we have our retrospective events that take place in our Scrum teams. If anybody would see that we are falling short on our effort to keep up our quality standards, they could raise this and we would come up with an action item.

Maintenance

For quite some time, the TEM was a Google doc, open to all of our engineers for commenting. We also had a separate spreadsheet, where they could add their suggestions. It could be anything from a new guideline, to removing an existing rule or refining a process. Engineers could also “vote up” another person’s suggestion. This spreadsheet was used a lot, adding dozens of valuable suggestions.

The Quality Standards Committee would meet once a month and discuss these suggestions, as well as items of our own. Taking into account all the feedback, the committee would decide what to do, which could result to a new guideline. Then, we would (internally) publish a new version of the document and notify all engineers.

We still have the same process, with the difference that the TEM is now on Github Pages instead of Google docs. This change was made when we decided to make the TEM public. The QSC team still meets once a month and discusses the current state of things and how to move forward, always taking into account all feedback that keeps coming in (albeit in a slower pace, since our guidelines have matured significantly since we started).

Final thoughts

From the start, we decided that we’ll have an agile mentality when it comes to running this initiative. The recurring meetings of the Quality Standards team help us keep this effort alive; we discuss how it’s going, its adoption from the engineering team, as well as any issues we might have to deal with. There were times that we had to adapt to a poor adoption of a specific guideline, making things less strict at first, and -after that didn’t solve the problem- introducing more automation in the process.

So far things are going very well and the process we have created around this seems to help a lot. We aim to keep working on it and improving it even further!