Working agreements, engineering metrics and developer portals

Engineering metrics alone aren’t enough. Nor are developer surveys.

To drive continuous improvement, managers need a way to go beyond metrics and drive real change. And driving change is best when everyone feels they have a say and skin in the game.

That’s where working agreements come into play. Instead of saying “we want to improve DORA metrics” managers can help teams arrive at working agreements, which are a set of guidelines for teams to get the best from each other. In turn, working agreements can change habits and drive significant improvement.

You can change engineering metrics and culture for the better by using working agreements to ensure:

• Time to review of pull requests
• Work in progress targets and 
• Cycle time targets

The result: more deep work and less delays and frustration. Additionally, a culture of more accountability, better communication among teams and the transparent discussion of work behaviors that will drive a more positive work environment.

And the best part: you can do all this with an internal developer portal.

Lets see how:

What are working agreements? 

Working agreements are clear expectations on how developers work together around processes. They are a set of guidelines on how teams and developers can get the best from each other. The focus of working agreements is on the operational aspects, setting norms and expectations for daily collaboration. The goal here is to change habits through the definition of the working agreement. 

These agreements establish measurable targets for key areas such as

• Pull request review time (how long it takes to review and merge code changes) 
• Work in progress targets for issues
• PR size
• Bug resolution time (how long it takes to fix reported bugs), and 
• Code quality metrics. 

By defining clear expectations and setting concrete goals, working agreements create a shared understanding of what success looks like and provide a framework for achieving it together.

Why do you need working agreements? 

In the absence of working agreements, engineering teams often struggle with misaligned expectations, inconsistent practices, and a lack of clarity around goals. Even when general goals are agreed upon, such as quick cycle times, better communication, elimination of bottlenecks, they are not necessarily broken down in a way that lets teams and developers truly own them.

Working agreements address these challenges by providing a shared understanding of what is expected from each team member and how the team will function as a whole.

By establishing clear guidelines and measurable targets, working agreements help teams:

• Increase accountability: Working agreements hold team members accountable for their commitments, ensuring that everyone is working towards the same goals.
• Enhance productivity: By eliminating ambiguity and streamlining processes, working agreements help teams focus their energy on delivering value, rather than getting bogged down in disagreements or misunderstandings.
• Track progress and identify areas for improvement: The measurable targets in working agreements allow teams to track their progress over time and identify areas where they can improve their performance.
• Improve collaboration: When everyone knows what is expected of them and how they should interact with others, collaboration becomes smoother and more efficient.

In short, working agreements provide a roadmap for success, helping engineering teams navigate the complexities of their work and achieve their goals together.

Since internal developer portals are an excellent place to consolidate all engineering metrics, and to also drive new habits through reminders, initiatives and dashboards, they are both the place where teams and managers can assess where to drive change and to actually make it happen.

The challenge of working agreements

While working agreements are a valuable tool for engineering teams, they often face a significant challenge: transitioning from theory to practice. It's easy to craft a well-intentioned set of agreements, but ensuring they are consistently followed and actively contribute to the team's success is another story.

One common pitfall is the "wiki graveyard" scenario. Teams create working agreements, document them meticulously in a wiki or shared document, and then forget about them. These agreements become buried in a sea of information, rarely revisited or updated, and ultimately lose their relevance and impact.

Even when teams make a conscious effort to reference their working agreements, actively tracking and measuring their compliance can be time consuming. Without a dedicated system, it's easy for these agreements to fall by the wayside as the team gets caught up in the daily grind of deadlines, deliverables, and urgent tasks.

How to set working agreements 

Begin by understanding the core engineering metrics in your internal developer portal: anything from PR-related metrics, to issue counts, standards and classic metrics such as DORA metrics and more. Using surveys to ask questions about habits, sentiments and more, can be useful too.

Once you understand the metrics, formulate some ideas about how to drive change - which behaviors should be changed and how. Then you need to work on creating buy-in with the team.

• Gather the Team: Schedule a dedicated meeting with the entire engineering team. Make sure everyone understands the purpose of the meeting and the importance of working agreements.
• Brainstorm and Discuss: Facilitate a collaborative brainstorming session to identify the key areas where working agreements are needed. Encourage everyone to contribute their ideas and perspectives. Discuss potential challenges, concerns, and how to address them.
• Define and Document: Based on the discussions, define specific, measurable goals and expectations for each area of the working agreement. Document these agreements clearly and concisely, ensuring everyone understands and agrees on them.
• Measure and Adapt: Regularly track and measure the team's progress against the agreed-upon goals. Use data and metrics to assess the effectiveness of the working agreements. If necessary, make adjustments to the agreements to ensure they continue to support the team's evolving needs and goals.

Working agreements in a developer portal

A developer portal can transform how working agreements are created, tracked, and maintained. Using the portal's scorecard feature, teams can translate their working agreements into measurable metrics. For example, a team might set targets for deployment frequency, average pull request review time, or the number of open bugs. These metrics are then automatically tracked by the portal, pulling data from integrated tools like version control systems, code review platforms, and issue trackers.

This real-time tracking ensures that working agreements are no longer abstract concepts but living. Team members can easily see how they are performing against their agreed-upon standards. When everyone knows what's expected and where they stand, it encourages teams to meet and exceed those expectations.

Furthermore, the portal's reporting capabilities provide valuable insights into the team's overall performance. By visualizing trends and identifying areas for improvement, teams continuously refine their working agreements. This iterative process ensures that the agreements remain relevant and effective over time.

The developer portal can be leveraged to create custom dashboards for team leaders, providing an overview of the team's performance against their working agreements. This allows for quick identification of potential bottlenecks or areas where additional support may be needed. 

Additionally, the portal can generate notifications when teams are not meeting their agreed-upon targets, fostering a culture of accountability and continuous improvement. 

Conclusion

Working agreements are a powerful tool for engineering teams, but only if they're actually used. A developer portal can bring these agreements to life, making them a central part of your team's daily work. With tracking, reporting, and alerts, you can easily see how you're doing and where you can improve.

Interested in seeing how this works? Let's set up a demo and explore how a developer portal can help your team succeed.