Forem: Ari Koponen

6 ways developers can learn more at work

Ari Koponen — Wed, 05 Jan 2022 00:00:00 +0000

We know from multiple studies (e.g., 1, 2, 3) that learning at work improves both job satisfaction and organizational commitment. Both of these contribute to higher productivity and lower turnover.

Many companies use personal learning budgets and some type of "5%/10%/20% time" policy to encourage learning. These are useful but highly dependent on personal motivation and learning habits. It’s often hard for software developers to prioritize learning over their busy day-to-day work. For example, only around 10% of Googlers are using their famous "20% time" policy.

The best way for a software developer to learn is by having a role and a project where they can learn through their day-to-day tasks. That’s why companies should build a culture where learning is part of the developers’ job instead of an "add-on." This helps with motivation and allows people with little free time — like the parents of small children — to continue learning.

Here are six proven ways to do that.

1. (Good) code reviews

Code reviews offer a great opportunity to learn because the feedback you get in a code review is highly contextual and often very specific. When you discuss why one solution is better than another, you can develop your professional intuition in a way that’s very hard to achieve otherwise.

Learning happens in code reviews only if they’re done well. If your team suffers from rubber-stamping "LGTM" code reviews and you want to improve them, you can check this complete guide to code reviews from Kimmo Brundfeldt.

2. Pair programming

During pair programming, you watch another person write code or hear them discuss a solution. This allows you to pick up practical tips on improving your work (e.g., how to use your editor). You also learn new ways of thinking and solving problems.

Pair programming costs less than most people think. In addition to improving technical skills, it also improves design quality, reduces defects, reduces staffing risk, improves team communication, and is often considered more enjoyable than working alone.

Tuple’s excellent Pair Programming Guide covers everything from getting started with pair programming to scientific research on the subject.

3. WIP limits

Developers often prefer to work alone on tasks and issues, even when the work could be split into smaller tasks and worked on side-by-side. Developers feel more productive when they don’t have to deal with the "overhead" of coordinating with others. However, this often leads to more siloing of knowledge and less knowledge sharing within the team.

Many people know work-in-progress (WIP) limits only as a Lean/Kanban to improve the flow of work. But having a sensible WIP limit improves learning through collaboration. As an added bonus, it also leads to much better code reviews.

You can take a look at this blog post on decreasing issue cycle time to figure out if you’re working on too many things simultaneously and would benefit from WIP limits.

4. Design documents

Design documents, RFCs, or just "documented plans" are a great way to enable learning on the job. When done well, the document explains why the chosen solution is the best from both product and technical perspectives. It considers the tradeoffs of different approaches and highlights the most important non-functional requirements that contribute to the solution, like accessibility, performance, and user experience.

Reading a highly contextual document like this allows developers to learn how other — often more experienced — people think about technical decisions. The developers writing the design documents also learn valuable skills: system design, communicating technical decisions, and how to motivate and inspire peers to adopt a solution.

To get started, learn how to plan together as a team and check out Gergely Orosz’s article on design documents.

5. Study groups

Organizing study groups within your engineering organization is a great tool for peer-to-peer learning. This is especially true when you have more than a handful of developers spread across multiple teams. Trying to apply books or courses to day-to-day work is not always easy — and may lead to people "trying out stuff" on your codebase just to learn. When people who work in the same context discuss the material, it’s easier to identify valuable learnings.

Often, the best part of study group meetings is going beyond the material by having people share their own experiences and different angles on the subject. This is especially true for books/materials that cover high-level principles (e.g., books like "Domain-Driven Design" and "Working with Legacy Code.")

I’m planning on writing a full guide on running great peer study groups (let me know if you’re interested in reading it.) For now, these are the steps we used at a company with 350+ developers to run study groups at scale:

Find a topic, a book, or a course that 4-10 developers in your organization are interested in. Optionally, find 1-2 "expert members" from your company who can participate. Choose a person responsible for organizing the study group meetings.
Set up a 30-60 minute meeting with a weekly recurring calendar invite for the study group. The larger the group, the more time you need. The meeting can be an extended company-paid lunch.
For every meeting, choose a section of the material that everyone can go through beforehand. E.g., for books, we used less than 50 pages. Participants are expected to go through this material at their own pace in between meetings.
Start the meetings by having everyone go through their notes or thoughts on the material. Discuss.

When the material for the study group is highly related to the participants’ current project, they can apply the learnings almost immediately. Other materials will usually pay dividends in the long run.

6. Peer-to-peer sharing

One of the best ways to get excited about learning is through the people around you. This is why building a culture of sharing learnings with peers is so important. For example, you can watch engineering talks together, share links to interesting content on company Slack, or have sessions where team members share their knowledge on some topic.

Not everyone will read every excellent blog post on Slack or attend every session, but whenever they do, they’re likely to learn something useful. Positive learning experiences create a virtuous cycle and motivate people to learn more.

Share your own experiences

What has worked for you? Have you tried out any of these practices? How can software developers learn on company-time?

100 Tips on Software Developer Productivity

Ari Koponen — Wed, 15 Dec 2021 09:40:44 +0000

I've developed software professionally for the past 10 years. Here's a list of 100 things I've learned about software developer productivity.

At the beginning of your career, learning to "code fast" significantly impacts your productivity. Once you're "good enough," the impact substantially diminishes. Pay attention to when this happens.
Don't be too proud to try and" hack your mind." Many productivity tips that sound patronizing actually work.
Write your tasks down and use a to-do list.
Having a tangible goal will make you move faster.
Procastination is normal. Start by writing a single line.
What works for someone else might not work for you.
Try Pomodoro. It might work for you.
Learn what makes you productive.
Set boundaries that enable you to work in a way that makes you productive.
Strong intrinsic motivation and curiosity trumps all productivity hacks.
Learn how to tap into your intrinsic motivation.
Pair program and watch other people code. You might pick up a skill or two that help you work faster.
Your intuition affects your productivity more than you know. Pay attention to cultivating a good intuition.
Learning out of a bad habit takes work. Invest in learning good habits.
Saying "yes" to everything will destroy your productivity. You need a personal WIP limit.
Being obsessed about your work will make you temporarily more productive but burn you out if stretched for too long.
Physical exercise, eating healthy, and sleeping well do not take away, but contribute to your productivity.
Take regular breaks (e.g., 10 minutes every 50 minutes).
Trying to work in too long stretches will teach your brain to start wandering off to memes and hot takes on Twitter.
Make sure you have enough focus time for deep work and "flow."
Disable all the notifications you can.
Being in "flow" makes you feel productive but does not always mean you're making progress.
You can spend hours polishing an abstraction but deliver zero customer and business value.
Being productive does not mean you're making an impact. Work hard on things that matter.
The more experience I get, the more I'm interested in improving how my team or organization works together vs. optimizing my individual productivity.
When solving technical problems that require collaboration, the bottleneck for individual developer productivity is not your ability to write code but the team's ability to create viable solutions.
Most problems in building great software products require collaboration. Your ability to collaborate will become a bottleneck.
You will be more productive in some teams/companies than others.
Eventually, the bottleneck for your productivity will be the team and organization surrounding you.
Developer productivity and compensation don't often go hand in hand.
Some companies will compensate you more for the same work than others.
The best "10x engineers" are the ones who 10x the team and people working around them.
Delegate and help other people. Learn to celebrate their success.
Learn to use automation. Removing errors and reducing cognitive load has a more significant impact on your productivity than "working faster."
Developer experience and ergonomics matter.
Automatically format your code with a deterministic code formatter like Prettier or Black.
Use a linter. Learn how to write custom rules to match the way your team works.
Write automated tests. Life is too short for constantly fixing trivial bugs.
Setting up a Continuous Integration (CI) pipeline is likely easier than you think. Learning how to do it will save you time in every future software project.
Keep feedback loops fast.
Automatically deploy to production.
Keep your build times low.
Make sure developers can run the test suite on their computers.
Enable automatically running related tests on file changes.
Use feature flags to allow shipping work faster to production.
You might not need a staging environment.
You might benefit from a staging environment.
It depends.
Developers using Vim look like they're much more productive than the rest.
Don't always pick the tasks that make you feel most productive. It will stagnate your learning and make you feel that you're not moving forward.
Prioritize reviewing code. It will help your team stay productive.
Every time a developer prioritizes reviewing code, a new star is born in the Torvalds & Carmack galaxy.
Being "agile" has very little practical meaning.
Calculating velocity and story points rarely help teams improve their productivity.
Small, practical change based on data trump "agile transformation."
The goal of planning is to split the elephant into bite-sized pieces.
Developers often prefer working alone on large tasks for long periods.
Developers working alone on large tasks for long periods rarely result in the smallest possible increment being shipped fast.
Working together on a task is often less productive in the short run.
Working together on a task improves learning and is often more productive in the long run.
With large codebases, developer productivity largely depends on their knowledge of the system.
Splitting large codebases into modules helps new developers become productive faster.
Modular architecture only works if the API contracts are clear and modules are truly decoupled from each other.
Sometimes, a developer is more productive than others only because they have more knowledge and power.
A single developer owning a disproportionate amount of knowledge and power in a team will lead to some developers underperforming.
A "10x engineer" born out of owning a disproportionate amount of knowledge and power is an anti-pattern and will lead to capable developers leaving your company. Avoid it at all costs.
Measuring developer productivity only through activity (e.g. # of commits or PR reviews) does not work.
Trying to condense developer productivity into a single metric will fail and make developers lose their trust in the company's management.
Measuring individual developer productivity is hard. If you try to do that, you will likely lose more than gain.
When trying to measure developer productivity, data quality is crucial. Bad decisions made based on poor data are costly.
There is much more reliable research on software developer productivity than most developers realize.
Focusing on team and organizational level developer productivity will yield the best results.
Reading the book "Accelerate" and understanding the SPACE framework will give you a good start to understanding development team productivity.
When measuring developer productivity, you should have multiple metrics that complement and challenge each other.
The subjective experience of developers is valuable data.
Only relying on the subjective experience of developers is not enough. Especially when trying to improve development productivity across the organization.
Improving software team productivity is largely about trying to improve the flow of work while keeping quality high and working at a sustainable pace.
Measuring your team's cycle time and deployment frequency will help you improve your flow of work.
Knowing how much time your team spends fixing bugs vs. feature work will help you prioritize writing tests, fix technical debt, and keep your quality high.
Developing software is a marathon, not a sprint. Optimize accordingly.
Teams should be in charge of improving their own productivity and have access to the necessary metrics and tools.
Individual developers benefit from understanding what affects their teams' overall productivity.
Most teams try to do too many things at the same time. You need a WIP limit.
WIP limits improve collaboration and help you ship the most important stuff.
WIP limits reduce procrastination on hard tasks.
WIP limits combined with good prioritization help individual developers work on things they're not familiar with and encourage learning.
Encouraging learning makes software developers more productive in the long run.
Consistently good work is better than heroics.
Organizations that put heroism above consistently good work perform worse in the long run.
Developers love to measure everything else but their own productivity.
Early attempts at measuring software developer productivity ruined the whole thing for most developers.
It is hard to recover from industry trauma.
Don't focus on measuring individual developers if you're trying to improve your company's software development speed.
Learning about Lean and Queuing theory is valuable when improving software team productivity.
Consultants have done a great job ruining Lean for the rest of us.
Measuring software team productivity can make engineering teams happier.
Measuring software team productivity only makes teams happier and more productive if they're on board.
If developers are not on board, your metrics will be gamed.
Not giving your developers proper autonomy and control over their work will make them unhappy. Do not micromanage.
Happy engineers are more productive.

See and share on Twitter

You can see these tips in Twitter thread here:

// Detect dark theme var iframe = document.getElementById('tweet-1471028936314339330-817'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1471028936314339330&theme=dark" }

Reduce bias in retrospectives with better data

Ari Koponen — Wed, 27 Oct 2021 10:31:16 +0000

Many software organizations run retrospectives based on mostly subjective data collected from the retrospective participants. Studies show this leads to skewed insights that often miss broader organizational goals. One solution is to add a step to your retrospectives in which you present relevant hard data gathered from a wide array of data sources.

I recently wrote a blog post on well-researched advice on software team productivity that included a summary of a few excellent studies on the effectiveness of retrospectives. These studies highlight how teams often rely too much on the subjective personal experiences of the team members to collect data for the insights and actions generated from the retrospectives.

[Retrospective] discussions might suffer from participant bias, and in cases where they are not supported by hard evidence, they might not reflect reality, but rather the sometimes strong opinions of the participants.

~ Lehtinen et al. (2014)

Retrospectives focused on the personal experiences of the participants often work as great team-building events. The challenge is that retrospectives based only on subjective data collected from the participants are susceptible to multiple cognitive biases like recency and confirmation bias.

As these retrospectives often miss some crucial pieces of data, they may result in false insights. False insights result in actions that are at best a waste of time, at worst, a hindrance to the organization's goals.

What a data-driven retrospective looks like

There is a multitude of ways you can run a retrospective. This blog post will use the 5-step retrospective structure from the book "Agile Retrospectives." It is one of the most well-known options and is a great, generally applicable approach to running a retrospective. Most retrospectives we've seen teams run use at least some parts of its structure.

The five steps of the structure are:

Set the stage : Help people focus on the work at hand. Reiterate the goal. Create an atmosphere where people feel comfortable discussing issues. Get everyone to say a few words.
Gather data : Collect the data you need to gain useful insights. Start with the hard data like events, metrics, features, or stories completed. Continue with personal experiences and feelings.
Generate insights : Ask "why?" Think analytically. Examine the conditions, interactions, and patterns that contributed to successes or failures. Avoid jumping to the first solution, and consider additional possibilities to make sure you address the actual root cause.
Decide what to do : Pick the top items from the list of improvements. Decide the actions you are going to get done. Assign the actions to individual people.
Close the retrospective : Decide how to document the results, and plan for follow-up. Ask for feedback about the facilitation/retrospective.

Five steps of a retrospective: a personal-experience-centered version using sticky notes

When running a data-driven retrospective, our focus is on the second step, "gather data." You should start the step by first gathering "hard data like events, metrics, features, or stories completed" and then continue to the personal experiences and feelings of the participants.

However, many teams more or less skip the first part. I've seen dozens of retrospectives where the organizer rushed to ask questions from the group like "What went well? What could be improved? What went badly?" without first thinking about the context.

To fix the situation, we can add an explicit step that we'll call "present hard data." Trying to gather hard data combined with personal experiences and feelings is a historic relic. Traditionally, retrospectives have been promoted by "agile people" and consultants—external facilitators. Thus, most retrospective advice is written for these kinds of "outsiders."

An outsider needs to start with "gathering all the data" because they don't often have access to it outside the retrospective. If you're running a modern software organization that employs retrospectives, you have no reason to do a separate data inventory every time. Your "hard data sources" are not likely to change often.

6-step retrospective with "present hard data" as a separate step

When we add the "present hard data" step to our retrospectives, we get four clear benefits:

Better focus: We don't need to spend time trying to gather the hard data from the participants. Spending a few minutes going through the most important data is enough. Then, the "gather data" section can focus on getting people to share their personal experiences and feelings.
More reliable data: Your data quality is better because the data is not based on only what people remember from the past.
Better insights: Consistent hard data helps the participants generate better insights by reducing personal biases and making it easier to identify common patterns. This ultimately makes it more likely for the team to determine the actual root causes.
Continuous evaluation of your hard data: The step works as a great "mini-retrospective" on what hard data your team uses to drive its decision-making. If the presented hard data feels irrelevant for the team's continuous improvement, it is a sign that either your hard data or your team may be missing something.

How to get started with data-driven retrospectives

To get started with data-driven retrospectives, take inventory of the "hard data" sources you already have. Many organizations have KPIs, OKRs, or similar to make sure the teams in the organization are prioritizing the right things business-wise. You might also have insights from your version control system like GitHub and issue tracker like Jira. Sales and customer success data is also often valuable.

Then, think about what data you're currently not collecting but would need to get a holistic picture. For example, the SPACE framework is an excellent tool for this. Overall, your goal is to provide the people in the retrospective with an accurate timeline of what happened within the time period you're focusing on (e.g., last iteration or sprint).

It can be hard to correctly remember and jointly discuss past events in a constructive way. Fact-based timelines that visualize a project's events offer a possible solution.

~ Bjarnason et al. (2014)

You will likely identify hard data that you should have but cannot currently automatically gather. You can compensate for this by making a manual report or making sure you cover it when gathering personal experiences from people.

For example, many teams don't have very good insights into what kind of work they actually did during the last iteration. You can collect this information by answering these questions: "What did we ship? How much work went into the roadmap/toward our OKRs? How much went to fixing bugs?"

Another common practice used in many retrospectives is to start every session by building a manual timeline of the last iteration. This reminds people of the key events that may have contributed to the team's productivity and how everyone is feeling.

Example timeline of two quite busy weeks for a team. Can you connect the dots?

It is worth noting that the more automatic you can make your hard data sources, the better. If you rely on manual work in, for example, calculating the ratio between bugs and roadmap work, it is very likely that, at some point, your data will not be up to date.

Relying on manual work also often leads to the team dropping these metrics when they start feeling busy. This situation is precisely the opposite of what you want to achieve. If anything, you should have a clearer picture of what is essential when you're running low on time.

To be honest, I haven't personally seen a single team continually do great data-driven retrospectives unless the data and reports were automatically available.

A real-life example of holistic hard data

To give a real-life example of a diverse combination of hard data, I will describe the hard data sources we use at Swarmia. We have four different hard data sources: objectives and key results (OKRs), weekly customer reports, sales pipeline, and Swarmia's Work Log.

Objectives and key results (OKRs)

OKRs include the objectives that we feel are the most important goals for our business right now. Achieving these usually takes multiple months. Each objective has a few (2-6) key results to make them more actionable. We update the progress of our OKRs every Monday.

Especially in larger organizations, it can be easy to wander off from the things likely to have the most significant business impact. OKRs are an excellent data source for bringing those discussions into retrospectives.

Example of two engineering team objectives and related key results

Weekly customer report

Our weekly customer report contains key performance indicators (KPIs) such as monthly recurring revenue (MRR), number of paid seats, user activity, and Slack notification adoption. It provides retrospectives with the necessary context for evaluating if our decisions have been impactful and served our users well.

Example feature adoption graph with monthly, weekly, and daily active users (MAU, WAU, DAU)

Sales pipeline

We use Hubspot to track our sales pipeline. Seeing the pipeline is helpful even for the engineers. It often provides great context for the features that may be included in the roadmap and is an excellent source of information when discussing the differences between our customers and their needs.

When your organization becomes bigger, looking at the sales pipeline becomes less valuable. Because of this, our sales team also maintains a "Customer Feature Wishes" page that highlights the most common challenges across the deals.

An example Hubspot sales pipeline

Work Log

Work Log is Swarmia's unique feature that visualizes what has happened within a specific week. It allows us to see at a glance how much of our activities went into the roadmap (e.g., epics or stories) and how much attention we put into individual issues, bugs, and unplanned work. It includes most of the same information as the manually built "timeline" discussed above, except it automatically updates in real-time.

Swarmia Work Log showing work towards the roadmap, other planned work, bugs, and ad-hoc work

Conclusion

Hopefully, this blog post inspires you to include enough hard data in your retrospectives. It will allow your teams to create better insights and actions, ultimately leading to more productive teams and happier engineers.

You can still run retrospectives in which you put the hard data aside and focus on the feelings and personal experiences of the team. Having different kinds of retrospectives will benefit your team and help keep people engaged.

However, ensure you rely on a wide array of data sources when holding retrospectives on topics in which accurate insights are essential. Leaving hard data out of a retrospective should be a deliberate choice, not an accident.

4 resources on software team productivity everyone should know

Ari Koponen — Tue, 05 Oct 2021 07:05:07 +0000

Understanding how individual people and productive teams behave is crucial for improving team performance. Often, it can be hard to distinguish ideological advice from insights grounded in research. Here's a list of four reliable resources every software leader should know.

During my tech career, I've met a multitude of idealistic people who believe following idea X or methodology Y will somehow magically transform a team or an organization. In reality, if you want to make software teams more productive, there are no silver bullets.

Every software organization is different. People come from different cultures and circumstances. They have varying levels of experience, motivations, and personalities.

The only real way forward is a relentless process of incremental improvement:

Identify bottlenecks
Experiment with a possible solution
Measure
Analyze
Repeat

It’s simple advice but hard to put into practice. One of the biggest challenges in this process of continuous improvement is identifying what you should measure and what kind of behavior you should foster.

The four resources in this article will give you reliable advice that will help you make meaningful improvements in your organization.

Project Aristotle: Understanding team effectiveness

If you've heard that "psychological safety" is the most important factor for creating productive teams, you've heard about Project Aristotle. Project Aristotle is Google's most well-known and quoted research on what makes a team effective.

The main finding of this research: How teams work together is more important than who is on the team.

The five key dynamics that affect team effectiveness, in order of priority, are:

Psychological safety: Team members feel safe to take risks and be vulnerable in front of each other.
Dependability: Team members get things done on time with the expected level of quality.
Structure and clarity: Team members have clear roles, plans, and goals.
Meaning: Work is personally important to team members.
Impact: Team members think their work matters and creates change.

The researchers have also provided a list of improvement indicators for each key dynamic. These are signs that your team needs to improve a particular dynamic:

Psychological safety: Fear of asking for or giving constructive feedback. Hesitance around expressing divergent ideas and asking "silly" questions.
Dependability: Team has poor visibility into project priorities or progress. Diffusion of responsibility and no clear owners for tasks or problems.
Structure and clarity: Lack of clarity about who is responsible for what. Unclear decision-making process, owners, or rationale.
Meaning: Work assignments based solely on ability, expertise, and workload. There's little consideration for individual development needs and interests. Lack of regular recognition for achievements or milestones.
Impact: Framing work as "treading water." Too many goals, limiting the ability to make meaningful progress.

To understand how your team feels about these dynamics, you can use this tool. It gives you questions that you can discuss together, which will help your team determine their own needs and commit to making improvements.

DORA: Four key performance metrics

The DevOps Research and Assessment (DORA) team is a research group that started independently in 2014 and has been part of Google since 2019. They're known for the annual "State of DevOps" reports.

The DORA team has conducted seven annual global surveys between 2014–2021 that have collected data from more than 32,000 software professionals. From this research, the DORA team has identified four key performance metrics that indicate the performance of a software development team and their ability to provide better business outcomes.

These four "DORA metrics" are:

Deployment frequency: How often an organization deploys to production.
Lead time for change: The time it takes to get committed code to run in production.
Change failure rate: The percentage of production deployments leading to degraded service and remediation (e.g., rollback).
Time to restore service: How long it takes to fix a failure in production.

The first two metrics, deployment frequency and change lead time, measure the velocity of your engineering teams. The second two, mean time to recover and change failure rate, indicate stability. One of the main points of the DORA research is that successful teams can improve their velocity while still achieving great stability.

The four DORA metrics are the most popular and well-known part of this research. However, it includes many other important insights you should be aware of when applying the metrics. For example, the study lists 24 key capabilities that correlate with team performance.

The research methodology and results of the State of DevOps are explained in detail in the book Accelerate. It is a must-read for anyone interested in improving engineering team productivity.

While the DORA metrics are very useful, you should not take them as the one and only measure for improving engineering. The research is more focused on identifying things that correlate with a company's financial performance rather than being a roadmap for improving engineering.

SPACE: A framework for developer productivity

SPACE is a framework for developer productivity. It looks at developer productivity from the perspective of different organizational levels (individuals, teams & groups, and systems) and dimensions (Satisfaction & Well-being, Performance, Activity, Communication & Collaboration, and Efficiency & Flow).

A member of the DORA team and author of the book Accelerate, Nicole Forsgren, led this study. The goal of SPACE is to give a more complete and nuanced picture of developer productivity beyond the specific metrics included in DORA.

The SPACE framework aims to overcome the flaws of earlier attempts to measure developer productivity. These "myths and misconceptions about developer productivity" include:

Productivity is all about developer activity.
Productivity is only about individual performance.
One productivity metric can tell us everything.
Productivity measures are useful only for managers.
Productivity is only about engineering systems and developer tools.

To counteract these myths, the SPACE framework "provides a way to think rationally about productivity in a much bigger space." It lists five different dimensions of developer productivity you should measure instead:

Satisfaction and well-being: "Satisfaction is how fulfilled developers feel with their work, team, tools, or culture; well-being is how healthy and happy they are, and how their work impacts it." Example metrics include employee satisfaction, developer efficacy, and burnout.
Performance: Trying to measure performance through outputs often leads to suboptimal business outcomes. Therefore, for software development, performance is best evaluated as outcomes instead of output. Example metrics include reliability, absence of bugs, and customer adoption.
Activity: Countable activities that happen when performing work, such as design documents, commits, and incident mitigation, are almost impossible to measure comprehensively. Therefore, you should never use them in isolation and instead always balance them with metrics from other dimensions.
Communication and collaboration: How well do teams communicate and work together? Example metrics include discoverability of documentation, quality of reviews, and onboarding times for new team members.
Efficiency and flow: These "capture the ability to complete work or make progress on it with minimal interruptions or delays." Example metrics include the number of handoffs in a process, perceived ability to stay in flow, and time measures through the system (total time, value-added time, and wait time).

For a fuller picture of what is happening in your organization, the SPACE framework suggests that you have metrics for these dimensions on three different levels of your organization:

Individual
Team or group: People who work together.
System: End-to-end work through a system, e.g., the development pipeline of your organization from design to production.

The SPACE framework authors provide an example table with metrics for each dimension and organization level. It gives you a concrete idea of what metrics you could have in your organization. The metrics proposed in the example are quite GitHub-centric. This is natural as the SPACE framework researchers mostly work at GitHub and Microsoft (owner of GitHub).

The example table brings us to the biggest strength and challenge of the SPACE framework: You will have to make it your own. There are multiple options for what you could use as a metric in your organization, and the metrics you choose depend on what fits your culture and the data you have available.

There are three things to keep in mind with SPACE. First, you should include metrics from at least three dimensions. Second, you should include metrics from all levels of the organization. Third, at least one of the metrics should include perceptual measures such as survey data. Including perceptions about people's lived experiences can often provide more complete and accurate information than metrics gathered from system behavior alone.

When the above recommendations are fulfilled, you will be able to construct a more complete picture of productivity.

It is also likely that having multiple metrics will create metrics in tension. This is by design. Having a more balanced view should help you make smarter decisions and tradeoffs among your teams and the whole organization. It will also make sure you're not optimizing a single metric to the detriment of the entire system.

If you want to start applying the SPACE framework to your organization, you can take a look at our free editable canvas (PDF, Google Docs).

Retrospectives: We may be lying to ourselves

Software organizations often use retrospectives as a mechanism for continuous improvement. Many people have inherited this practice from some vein of agile thinking. Some hold them because they've personally had some good experiences with them, others because they feel that "they are a best practice."

Retrospectives can be an excellent tool for continuous improvement, and you should probably use them in some form if you're already not doing so. However, know that retrospectives have their limits. This study on retrospectives does a great job of highlighting some of the common challenges that you're likely to encounter.

First, team-level retrospectives are often "weak at recognizing issues and successes related to the process areas that are external to the concerns of the teams." Software teams often talk—or complain—about organization-level issues in retrospectives: collaboration with sales, product managers, general management, etc. However, this discussion rarely results in any tangible changes in the broader organization.

If you want to hold effective retrospectives and drive change, mainly focus on topics that the team can control or directly affect. Whenever the team regularly discusses subjects outside of their direct influence, make sure the feedback is addressed on the level of the organization, where real change can be created.

Alternatively, your team's understanding of the surrounding business and organization's goals may be incorrect. In these cases, aim to provide the team with more context.

Second, software team members have biases. For example, "the development teams tend to find people factors as more positive and avoid stating themselves as a target for improvement." The study also lists situations where the way the team felt did not correspond with the real-world evidence on what had happened during the past few weeks.

To counteract biases, don’t rely purely on the personal experiences of the team members. Instead, include "fact-based evidence to the retrospective in order to base the analysis on a more objective picture of the real situation." This study proposes the use of a visual timeline of project events collected from various sources. There are many ways you could do this with your team. You can check out Swarmia's work log as an example.

Godspeed!

I believe understanding the principles and mechanisms above will help you improve your software team's performance. This research also drives our product development at Swarmia. We've seen teams following this advice cut their cycle time by 40% within two months.

Our product condenses much of the above information within a single tool that is designed to give you easy access to all the key metrics and help you continuously improve. If you're interested in seeing what it looks like and how it might help your team, learn more or get started.

What resources do you yourself find reliable?

Busting the 10x software engineer myth

Ari Koponen — Tue, 21 Sep 2021 12:31:42 +0000

Leaders often feel proud of their high performers. In reality, having "10x engineers" in your software organization may be a sign of an organization that is set out to fail in the long run.

As an engineering leader, it is very tempting to focus on the few individuals performing well in your organization and build your success around these people. After all, they are – seemingly – the smartest and most reliable people who create the best solution in the shortest amount of time.

Everyone working in software engineering has seen people who seem to get much more done than others. If not "10x," then at least “5x” or “3x engineers”. When looking at just everyday information, it seems reasonable that some engineers are just inherently more productive than others.

However, the science behind "10x engineers" is not very solid. The most cited studies on the subject were done decades ago in a very different environment and – more importantly – with a fairly small sample size. One of the most interesting recent studies comes to a very different conclusion. In a controlled environment, the variation between most software engineers is much more modest. There is also a significant variation in how the same person performs across multiple tasks. A person who outperforms others in some task may be average in another. “In summary, while programmers are better and/or faster than others, the importance and scale has been greatly exaggerated.”

The myth of 10x engineers is a great example of confirmation bias at work.

What explains productivity differences, if not mere individual talent?

When we take into account the surrounding environment – the organization as a whole – it is easy to spot multiple factors that affect performance in addition to individual talent. Do these two engineers have the same experience with the technology at hand? How familiar are they with the system they're working on? Do they have the same ability to make decisions on the go? How easily can they get help?

Now, take a look at your “wow that person gets things done” -experiences with these factors in mind. They often become quite mundane. People love heroics and relish the possibility of working with “the best.” It is a comforting reality. Much nicer than being honest about the challenges and realities in the organization. The things that hinder performance. Things that often feel very hard – if not impossible – to change.

As a real-life example, I once worked with a company where the company’s leadership considered a specific developer infinitely better than the others. The company's CEO would walk into the space where the developers worked and loudly comment – even to outsiders – “sometimes it feels like X is the only developer who gets anything done.” The developer was visibly proud of the feedback. Others were left obviously demotivated.

No one talked about the fact that this particular developer had been developing the same system for the past 15 years, the first five almost alone. He relished being “the best." Wrote hard-to-understand procedural code to 5000-line files. Did not actively share knowledge with his peers. Over the years, some capable developers had joined the company. Most of them decided to move on. The ones left were happy to coast along and leave all the heroics to the “10x engineer.” As a result, the company had great difficulties in trying to scale its development efforts.

This is, of course, a very extreme example but illustrates the problem well. Having a tiny percentage of high-performing engineers is often a symptom of bigger organizational issues like siloing or imbalance in power and responsibility. It is not just the natural order of things that is impossible for you to fight against.

Building a better strategy for achieving business success

From the perspective of the business's overall success, finding a few 10x unicorn developers is not what will make it or break it for you in the long run. The real key to success is to improve the average performance of everyone in the company. This is – statistically speaking – a more viable strategy.

The likelihood for those unicorns staying in your company for 5 or 10 years is also very low – unless you have a somehow extraordinary company. Even if they stay, they’ll be changing teams – and every time, they leave the teams built around their behavior scrambling. Again, hurting your overall ability to execute your business goals.

Instead, improving your organization to make more people productive will reap the greatest benefits. It will allow you to hire more people who can succeed in your engineering organization. The broader you can turn the pool of people you feel “could do great work at our company,” the better your odds for scaling with success. This realization should make us more holistic. Turn our attention from individuals to groups of people: teams, departments, and the whole organization.

This is good news. There is plenty of good research on software team performance. If your team is struggling with too many bugs in production or you have issues with shipping changes quickly take a look at the DORA metrics. If your team does not collaborate well together or team members are not taking ownership, learn how to foster psychological safety. To understand the full landscape of developer productivity, check out the SPACE framework.

Whatever you do, the key to success is to understand your team's bottlenecks and take action together with the team to improve the situation. Some things need one-off changes. Other's require habits. All team habits should be documented into a common working agreement that everyone is aware of and follows. Useful habits compound over time and create productive teams and organizations.

TL;DR;

The best strategy for most companies is not a relentless focus on trying to hire “the best” in hopes of finding 10x unicorn engineers. Rather, it is to make sure that the normal, capable engineers you can hire and retain perform their best. The organizations that can turn ordinary teams into high-performing ones will be the winners – and the engineers in them too.

(Cover image: A 10x engineer at work in Chernobyl. The Hollywood Archive / Avalon)

Story of Pixel: How we made an off-the-shelf design system our own

Ari Koponen — Fri, 23 Jul 2021 10:52:23 +0000

How we used a ready-made design system as the basis of our design system, Pixel, but made it our own.

Background

Supermetrics has been doubling in size for the past five years. In the beginning, the product was just a single sidebar within Google docs, and most code was on the backend. UI possibilities and requirements were limited. Today, Supermetrics has multiple applications and around ten front-end developers working across five teams. For the company, great UX is among the most critical competitive advantages.

The front-end applications have grown organically over the years. Because of the history, many UI components were not reusable. Styles were copy-pasted between applications. Despite SCSS variables and naming conventions, there were consistency issues with colors, spacing, and font sizes.

Building the new design system was one of my most exciting projects while I was working at Supermetrics. I had joined the company last October, and one part of my job description was "redesigning our Team site with our Head of Design." The main business drivers for the redesign were that development was slow, the UI was inconsistent, and it was hard to support the new most important user flows. Previously, the UI was mainly used for license and team management and was structured around those needs. Now, users have more complex needs like configuring and monitoring data transfers. This requires a very different approach to the UI.

Redesigning the Team site is a significant undertaking. It is Supermetrics' biggest custom UI written in React, TypeScript, and SCSS with hundreds of components and almost 100K lines of code. Redesigning it would also lead to updating the UIs of other applications to keep a consistent user experience across the product suite.

The Goal

We started discussing with our Head of Design Ivana Pesic and some of the front-end developers what would be the best way for us to achieve our business goals: supporting the new flows, consistency across all our apps, and making development faster. One of the most promising ideas was to build a design system. This would allow us to have a central repository of UI components and assets together with accompanying guidelines and documentation.

Our team was already somewhat familiar with the concept of design systems but wanted to make sure it was a worthwhile undertaking. We read about other companies' experiences and resources like Brad Frost’s Atomic Design book to improve our understanding. These gave us further confidence that a design system could help us sustainably reach our goals.

We set out to create a design system of our own with four goals in mind:

Consistently great UI. Make sure all teams could create UIs that feel like they belong together.

Shared vocabulary. Improve the communication between designers, developers, and other stakeholders in the company around designing and building UIs with great UX.

Educating people within the organization. Raise the bar of our UI/UX design across the whole organization by giving people tools that help them.

Improve speed of development. Stop reinventing the wheel and copy-pasting when it is not useful.

Choosing the approach

Once we knew why we were building a design system, it was time to decide how we'd do it. Should we build our design system from scratch or use an off-the-shelf solution? Building from scratch gives you more control and makes the design system reflect your company brand better. However, it is very time-consuming, and there are no real guarantees that the result is any better than using an off-the-shelf one. To make a decision, we needed to know what we needed.

To gather design requirements, we:

Did a component inventory of all the components we'd need.
Refreshed our brand book and style guide.
Made some designs to have an idea of the overall design style.
Researched many of the available options to have a general idea of what ready-made solutions were available.

On the technical side, we listed out the technical things we'd want to have:

Strictly-typed TypeScript. For great auto-complete and type-safety.
Maintainable CSS. For us, this meant: style-colocation, avoiding global scope, dead code elimination, and enforcing the design system styles, while still allowing one-off overrides.
Themeability. We knew we wanted to change the colors and fonts of any ready-made solution and themeability means that our changes are much less likely to break.
Tree-shakeability / ES modules. We knew all applications wouldn't use the whole design system, and we wanted the JavaScript bundle sizes to stay small for a great user experience.
Copy-pasteable component code. If we would need to modify some of the components heavily, we wanted to make sure we could use the original component as the basis.

With these requirements in mind, we researched if any of the ready-made options would fit. In this process, UXPin's Adele was very helpful. We found multiple promising options and dug a little deeper into them. At first, none of them seemed to fit our requirements, and we seriously considered building everything from scratch or using a UI component library like Chakra UI and adding the rest ourselves.

In the end, after much discussion and evaluation, we concluded Zendesk's Garden was the best fit for us in terms of technologies, default styles, and themeability. I sent the Garden documentation to some of our front-end developers for review, and all concluded that it looked good.

Making the design system our own

Although Zendesk's Garden matched our needs, we did not want just to copy their styles and call it a day. We gave the design system the name "Pixel" after our cute dog-mascot. We created a custom theme with our fonts, colors, shadows, and spacings. We also added some Supermetrics feel to the designs with small details like fully rounded buttons, SVG graphics, and hand-selected icons.

Also, on the technical side, we did not want our apps to depend directly on Zendesk's packages that we had no control over. We created a separate, privately hosted NPM package for Pixel, where we individually import and export the components that we want to use from Zendesk's packages. In this way, we can get all bug fixes and new features from Zendesk's Garden simply by updating our dependencies while still distributing our customizations to our own apps in a controlled way. We can also replace any part of the design system without affecting the consuming apps.

Pixel in action in our license checkout flow.

Lessons learned from building on top of a ready-made design system

As we expected, there are pros and cons to using a ready-made design system.

The pros

Fast time to use. The design system was used in three apps in less than six months from the start of the project.

A great technical foundation. The design system we chose had a ready-made Storybook and tests that we can use even when making changes to the components.

More concrete discussion. Our design discussions often start with the capabilities of the design system we're building on top of. This frames the discussion, allows us to find practical solutions faster, and helps us iterate in smaller steps.

The cons

Unscheduled fundamental discussions. With a ready-made design system, you skip important fundamental discussions. Our organization thinks differently about design than Zendesk. The differences often manifest themselves when we're designing and building a feature. Sometimes we've needed to start unexpectedly asking very fundamental questions about things like buttons and links or animations.

Dirty overrides to the ready-made components. We've aligned our designs to the limits of the ready-made design system as much as is feasible. Still, we have needed style overrides for, e.g., button variants. These overrides always feel a little bit hacky and may break at some point when the ready-made design system breaks.

Solutions

Accepting the trade-off we've made. We knew we were taking UI/UX and technical design debt when we chose to speed up things with a ready-made solution. This debt has to be paid back, and sometimes this happens at inconvenient times. Mentally accepting this and being prepared when working on new features helps.

Using a separate NPM package. We have mitigated most of the downsides of depending on an existing design system by our own private NPM Package. For example, we have already modified the Garden typography components heavily. We were able to copy-paste the original components to our package and modify them to our needs without making it feel hacky for consuming applications. We've also added a complete set of layout components inspired by SEEK's Braid design system, which we've built from scratch. For the consuming applications, there is no difference.

Future

In total, Pixel is now used in four different applications. The redesign of the Team site with Pixel has also begun, which makes the team super excited. The redesign will require many new UI components, some of which will belong to the design system and some which are application-specific.

In its current state, Pixel is still more like a component library than a full-blown design system. The documentation around the thinking on design philosophy and copywriting guidelines still need to be polished. The work has only begun, but now there is a great place to iterate and improve on.

What is it like to be an engineer at Supermetrics? 👉 supermetrics.com/careers/engineering

How to Disable Server-Side Rendering (SSR) in Next.js

Ari Koponen — Wed, 23 Dec 2020 08:05:49 +0000

Learn how to disable SSR in Next.js and use it to replace Create React App or any custom tooling.

Next.js is my absolute favorite tool for developing React applications. It offers you a best-in-class developer experience. It also has a ton of useful features for being more productive and optimizing your apps in production:

Static & server rendering
TypeScript support
Multiple entry points
Bundle-splitting and tree-shaking

However, in the past, I did not want to use it for all my React apps. Next.js does not work without server-side rendering (SSR) by default. I preferred using a non-SSR solution like Create React App, when my app did not require SSR, because SSR had caused me so many unnecessary problems.

Then, one day Tanner Linsley, the author of React Query, posted on Twitter that he was using Next.js without SSR as a replacement for Create React App:

// Detect dark theme var iframe = document.getElementById('tweet-1303818811322195969-826'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1303818811322195969&theme=dark" }

I was stoked! After a little bit of research, I was able to do this myself. 🤯

Why Disable SSR in Next.js?

SSR for React apps is necessary in a few cases:

The app's content needs to rank high on search results (SEO).
You need social-media previews (Facebook, Twitter, Slack, etc.).
You need the additional speed optimizations it can provide for your users.

However, using SSR has multiple trade-offs and challenges:

You need a complicated hosting environment. You cannot just upload your app to a server or a CDN. You need Node.js servers doing the server-side rendering. This adds complexity and also costs more.
You need to make sure your code works both on the browser and on the server (Node.js). This makes debugging harder and restricts you in some cases. For example, you cannot use localStorage to store authorization information, but you need to pass it in a cookie and use a cookie library that works on the server and the browser.

// Detect dark theme var iframe = document.getElementById('tweet-1230449374091784194-847'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1230449374091784194&theme=dark" }

It affects your application architecture. For example, server-side rendering needs to be done in a single render, so you need to fetch all the data for the page in a single location (like getInitialProps). This requirement complicates data fetching with libraries like Redux or React Query and often leads to duplicate code.

If you don't need SSR, these trade-offs are not worth it. Basically, you should consider disabling SSR for all apps where the UI is behind a login.

Heuristic: If your app is behind a login, you likely should disable SSR.

How can you disable SSR in Next.js?

Let's go through the steps for disabling SSR for a fresh Next.js application (created with npx create-next-app).

Step 1: Rewrite All Requests to `pages/index.js`

Next.js supports adding redirects. Create a file named next.config.js to the root of your project. Add the following configuration there:



module.exports = {
  target: "serverless",
  async rewrites() {
    return [
      // Rewrite everything to `pages/index`
      {
        source: "/:any*",
        destination: "/",
      },
    ];
  },
};

These redirects work only in the development environment. In production, you need to have a proxy server like NGINX or use your hosting platform's capabilities (e.g. Netlify's redirects) for doing these redirects.

Step 2: Disable SSR for Page Content

To disable SSR for page content, we need to add the following code to pages/_app.js:



import '../styles/globals.css'

function SafeHydrate({ children }) {
  return (
    <div suppressHydrationWarning>
      {typeof window === 'undefined' ? null : children}
    </div>
  )
}

function MyApp({ Component, pageProps }) {
  return <SafeHydrate><Component {...pageProps} /></SafeHydrate>
}

export default MyApp

In the code above, we wrap our page content to a component called SafeHydrate that allows us to prevent the page content from rendering on the server. Let's go through what is happening in the code above.

With Next.js you can check if we're on the server by checking if the window object is undefined.



if(typeof window === 'undefined') {
  // This code will only execute on the server 
  // and not in the browser
}

However, we cannot just wrap our code into this if-statement directly. If you try it, you'll notice that React will produce an annoying hydration mismatch warning in the console: Warning: Expected server HTML to contain a matching <div> in <div>. This happens, if the server HTML is different from what the browser renders.

In our case, it is safe to ignore this warning. To keep things tidy, we want to completely hide the warning from the console. This can be done by rendering a div with the prop suppressHydrationWarning. For better readability, we create a separate SafeHydrate component for this and wrap our page component into it.

Step 3: Check that Everything Works with `npm run dev`

Now, run npm run dev in your terminal. After the server is running at http://localhost:3000/ you should able to go to any URL (like http://localhost:3000/some/random/path) and see the content of index.js there.

Success! 🎉

Step 4: Build production bundles with `next export`

We want to deploy our app as a static bundle that can be served without a Node.js server. For this, Next.js offers the command next export. It will create a static version of your app in the out directory.

To use the command, update the "build" script in your package.json like this:



"scripts": {
  ...
  "build": "next build && next export"
  ...
}

Now, run npm run build. When you see the message Export successful, congrats! You now have a working static Next.js app in the out directory. 🎉

You can check the whole example app from this Github repository

Notes on Routing and other Advanced features

Routing

Next.js does not support dynamic routing if you don't have a server running. You need a router like react-router. The setup is the same as with other tools like Create React App.

Updating the `<title>` and Other `<head>` Tags

You don't need to add something like react-helmet for updating the head, Next.js <Head /> component will work.

Having Multiple Separate Pages

If you want, you can still use Next.js pages to have multiple different pages as separate entry points for your app. This will make your bundles per route smaller and speed up your development environment because only a part of the app will be built when you make changes.

For example, if you have a page /accounts you can create a file pages/account.js and add a corresponding rewrite:



module.exports = {
  target: "serverless",
  async rewrites() {
    return [
      // Rewrite everything under `/account/ to `pages/account`
      {
        source: "/account/:any*",
        destination: "/account",
      },
      // Rewrite everything else to `pages/index`
      {
        source: "/:any*",
        destination: "/",
      },
    ];
  },
};
```

# How's this different from using Next.js `getStaticProps` with `getStaticPaths`?

Using `getStaticProps` with `getStaticPaths` allows you to do Static Site Generation (SSG). This means that all the pages in your app are generated as individual `.html`-files when you run `npm run build`. 

SSG is awesome, but has a single big limitation: **You need to know all the paths your app has ahead of time**. This is not possible with many apps that have tons of user-specific paths like `/my-payments/123121521241`. 

With the approach described in this article, you can use a dynamic router like `react-router` with Next.js just like you would with Create React App or any traditional single-page app.

# Additional Resources:

- [This wonderful gist by @tannerlinsley](https://gist.github.com/tannerlinsley/65ac1f0175d79d19762cf06650707830)

How to Create a ButtonGroup Component with React and Tailwind CSS?

Ari Koponen — Sat, 16 May 2020 12:30:19 +0000

Button groups are a great example of a situation where you need to alter the styles of a child component based on its position within its parent. Doing this in React can sometimes be tricky, and styling components with Tailwind CSS adds its flavor to the challenge.

Let's recreate this Tailwind UI button group as a React component:

The JSX for this component might be something like this:

<ButtonGroup>
  <Button>Years</Button>
  <Button>Months</Button>
  <Button>Years</Button>
</ButtonGroup>

There are several different ways we could style these components with Tailwind in React. I will go through four different approaches that each teach you something new about handling parent-child relationships and styles in React.

Method 1: PostCSS @apply

View in Codesandbox

This method utilizes Tailwind's @apply directive. If you've used Tailwind outside of React before, this is likely very familiar to you.

With @apply, we can write normal CSS selectors and override our child styles. To do this, we add a .btn-group class to our <ButtonGroup /> component and .btn class to our <Button />. This is very similar to how Bootstrap handles button group styles.

Our CSS looks like this:

@tailwind base;
@tailwind components;

.btn {
  @apply relative inline-flex items-center px-2 py-2 border border-gray-300 bg-white text-sm leading-5 font-medium text-gray-500 transition ease-in-out duration-150 rounded-md;
}

.btn:hover {
  @apply text-gray-400;
}

.btn:focus {
  @apply z-10 outline-none border-blue-300 shadow-outline-blue;
}

.btn:active {
  @apply bg-gray-100 text-gray-500;
}

.btn-group {
  @apply relative z-0 inline-flex shadow-sm;
}

.btn-group > .btn:not(:first-child) {
  @apply rounded-l-none -ml-px;
}

.btn-group > .btn:not(:last-child) {
  @apply rounded-r-none;
}

@tailwind utilities;

And our React components look like this:

import React from "react";

const ButtonGroup = ({ children }) => {
  return <span className="btn-group">{children}</span>;
};

const Button = ({ children }) => {
  return (
    <button className="btn" type="button">
      {children}
    </button>
  );
};

function ButtonGroupExample() {
  return (
    <>
      <Button>Single</Button>{" "}
      <ButtonGroup>
        <Button>Years</Button>
        <Button>Months</Button>
        <Button>Years</Button>
      </ButtonGroup>
    </>
  );
}

export default ButtonGroupExample;

As you can see, our JSX <ButtonGroup /> and <Button /> components are minimal and have only a single class. All the styles are coming from our CSS file.

Pros 👍

Our JSX looks beautiful, as we can reuse our <Button /> component and just put it inside a <ButtonGroup />.
Easy to use, if you're already familiar with Tailwind (or CSS frameworks like Bootstrap).
Component class-attributes are short (instead of tens of classes, vs. examples below).

Cons 👎

We're writing quite a bit of new CSS for our components, instead of just reusing Tailwind's styles. This can quickly bloat our CSS file size.
Every change to our component styles will cause all of our CSS to be rebuilt, which can make development slow.
You have to invent new class names for all of your components. .btn and .btn-group are quite straight-forward, but sooner or later you might end up with something like .common-navigation__top-right-navigation--wide.
Our component styles are not visible in the components, and we might forget to delete them when we delete the components.

Method 2: Pseudo-Class Variants with Class Overrides

View in Codesandbox

In this approach, we utilize Tailwind's pseudo-class variants and the classnames library to override styles for the first and the last button in the.

In order to do this, we need to add a new component that we will name <ButtonGroupButton /> (I know, the name sucks!). If we added our pseudo-class variants to our <Button /> component, it would break when it would be the first or last child of its parent.

In this approach, our CSS has just Tailwind's basic styles:

@tailwind base;
@tailwind components;
@tailwind utilities;

And our JSX has plenty of classes:

import React from "react";
import classnames from "classnames";

const ButtonGroup = ({ children }) => {
  return <span className="relative z-0 inline-flex shadow-sm">{children}</span>;
};

const Button = ({ children, className }) => {
  return (
    <button
      className={classnames(
        "relative inline-flex items-center px-2 py-2 border border-gray-300 bg-white text-sm leading-5 font-medium text-gray-500 hover:text-gray-400 focus:z-10 focus:outline-none focus:border-blue-300 focus:shadow-outline-blue active:bg-gray-100 active:text-gray-500 transition ease-in-out duration-150 rounded-md",
        className
      )}
      type="button"
    >
      {children}
    </button>
  );
};

const ButtonGroupButton = ({ children }) => {
  return (
    <Button className="-ml-px first:ml-auto rounded-r-none rounded-l-none first:rounded-l-md last:rounded-r-md">
      {children}
    </Button>
  );
};

function ButtonGroupExample() {
  return (
    <>
      <Button>Single</Button>{" "}
      <ButtonGroup>
        <ButtonGroupButton>Years</ButtonGroupButton>
        <ButtonGroupButton>Months</ButtonGroupButton>
        <ButtonGroupButton>Years</ButtonGroupButton>
      </ButtonGroup>
    </>
  );
}

export default ButtonGroupExample;

Did you notice, how <ButtonGroupButton /> uses the pseudo-variant classes first:rounded-l-md last:rounded-r-md in order to override our button styles? If you try to do this on a normal Tailwind CSS installation, it won't work. The reason is that by default, Tailwind does not generate these pseudo-variants for border-radius classes. We need to configure our variants in order to add "first" and "last" pseudo-variants. The same is true for first:ml-auto.

In practice, this means that we need to change our tailwind.config.js "variants" section to this:

module.exports = {
  ...
  variants: {
    margin: ["responsive", "first"],
    borderRadius: ["responsive", "first", "last"]
  },
  ...
};

Pros 👍

Our styles are visible in the components themselves, so we can see what is going on right inside the components.
We have an explicit <ButtonGroupButton /> that has the styles specific for button group child buttons.
If we delete our components, we won't leave dead CSS to our project.

Cons 👎

Overwriting <Button /> styles outside the component itself is quite tedious. For example, we have to use rounded-r-none rounded-l-none instead of simply rounded-md. Otherwise, the override won't work.
<Button /> component has to allow overriding its styles with additional classes, which means that its styles are no longer strictly encapsulated.
We need to update out tailwind.config.js variants, which adds to our CSS build time. Moreover, it is very hard to know when we should remove the extra variants when we delete code.

Method 3: Passing Additional Props to Children Using React.cloneElement

View in Codesandbox

What if we would like to get rid of the <ButtonGroupButton /> component in the above example? This is possible by using React's cloneElement. This trick is found in the wild, e.g. in reach-ui's tabs.

For this method, our CSS and tailwind.config.js is identical to Method 2. We only change our components. We remove the <ButtonGroupButton /> and move its className override to the <ButtonGroup /> component:

import React from "react";
import classnames from "classnames";

const ButtonGroup = ({ children }) => {
  return (
    <span className="relative z-0 inline-flex shadow-sm">
      {children.map(child =>
        React.cloneElement(child, {
          className: classnames(
            "-ml-px first:ml-auto rounded-r-none rounded-l-none first:rounded-l-md last:rounded-r-md",
            child.props.className
          )
        })
      )}
    </span>
  );
};

const Button = ({ children, className }) => {
  return (
    <button
      className={classnames(
        "relative inline-flex items-center px-2 py-2 border border-gray-300 bg-white text-sm leading-5 font-medium text-gray-500 hover:text-gray-400 focus:z-10 focus:outline-none focus:border-blue-300 focus:shadow-outline-blue active:bg-gray-100 active:text-gray-500 transition ease-in-out duration-150 rounded-md",
        className
      )}
      type="button"
    >
      {children}
    </button>
  );
};

function ButtonGroupExample() {
  return (
    <>
      <Button>Single</Button>{" "}
      <ButtonGroup>
        <Button>Years</Button>
        <Button>Months</Button>
        <Button>Years</Button>
      </ButtonGroup>
    </>
  );
}

export default ButtonGroupExample;

Pros 👍

The same pros as Method 2, except we now don't need a separate <ButtonGroupButton /> for <ButtonGroup /> to work.

Cons 👎

The same cons as Method 2.
React.cloneElement is not commonly used and might confuse developers.

Method 4: Fully Separate Styles for Button and ButtonGroupButton

View in Codesandbox

If the class overrides in all of the previous methods make you feel iffy, you can choose to have totally separate components for <Button /> and <ButtonGroupButton />. This might make you yell, "hey, duplicating components is not DRY!" or ask, "what happens when I update my Button styles?" Neither one of these is a problem.

The reason is that on a contextual level, our <Button /> and <ButtonGroup /> components are tightly coupled. In practice, this means that whenever you make a change to <Button />, you'll have to check that you did not accidentally break our <ButtonGroup />. In most applications, you cannot contextually separate the too, because in most cases, the definition for how the <ButtonGroup /> should look is something like "multiple <Button />s next to each other, but a bit different."

If you look closely at the code in previous, there are multiple possible changes to the <Button /> component that would break our <ButtonGroup /> component:

We use the class-ml-px that adds a negative left margin to remove a "double border" between the buttons in the group. If we remove <Button />'s border or change its width, <ButtonGroup /> will break and has to be updated.
We use last:rounded-r-md to make the last button in the group has rounded borders on the right. If we remove <Button />'s rounded borders, <ButtonGroup /> will break and has to be updated.

Because of this contextual coupling, it will be very hard to create these components so that they will never break. You just have to remember to check that the styles in <ButtonGroup /> still work, whenever you change <Button />. Because of this, you might just decide to skip the tedious work of overriding classes and only share the common styles.

This is what I ended up doing when developing Tailwind button groups for morco.app. The result is like this:

import React from "react";
import classnames from "classnames";

const ButtonGroup = ({ children }) => {
  return <span className="relative z-0 inline-flex shadow-sm">{children}</span>;
};

const commonButtonClasses =
  "relative inline-flex items-center px-2 py-2 border border-gray-300 bg-white text-sm leading-5 font-medium text-gray-500 hover:text-gray-400 focus:z-10 focus:outline-none focus:border-blue-300 focus:shadow-outline-blue active:bg-gray-100 active:text-gray-500 transition ease-in-out duration-150";

const Button = ({ children }) => {
  return (
    <button
      className={classnames(commonButtonClasses, "rounded-md")}
      type="button"
    >
      {children}
    </button>
  );
};

const ButtonGroupButton = ({ children }) => {
  return (
    <button
      className={classnames(
        commonButtonClasses,
        "-ml-px first:ml-auto first:rounded-l-md last:rounded-r-md"
      )}
      type="button"
    >
      {children}
    </button>
  );
};

function ButtonGroupExample() {
  return (
    <>
      <Button>Single</Button>{" "}
      <ButtonGroup>
        <ButtonGroupButton>Years</ButtonGroupButton>
        <ButtonGroupButton>Months</ButtonGroupButton>
        <ButtonGroupButton>Years</ButtonGroupButton>
      </ButtonGroup>
    </>
  );
}

export default ButtonGroupExample;

Pros 👍

Styles are encapsulated in components.
Common styles are explicitly stated in code.
+ Same Pros as in Method 2.

Cons 👎

We still might accidentally break <ButtonGroup /> styles when changing <Button />'s styles. The common variable only gives a hint to the developer but does not "type-check" CSS class relationships.
If you add special behavior to your <Button /> component, you will have to duplicate this to <ButtonGroupButton />, or have some kind of <BaseButton /> that is used by both of these components.
<ButtonGroupButton /> still looks kind of ugly. 😜
We might not remember to remove the tailwind.config.js additional variants when we delete code.

Conclusion

There are multiple ways for achieving the same result when using React with Tailwind CSS. All approaches have their strengths, and what you end up going with depends on the practices that you and your team might like best.

What method do you think is the best? Why? Do you have a better way of creating a ButtonGroup with Tailwind CSS in React?

Forem: Ari Koponen

6 ways developers can learn more at work

1. (Good) code reviews

2. Pair programming

3. WIP limits

4. Design documents

5. Study groups

6. Peer-to-peer sharing

Share your own experiences

100 Tips on Software Developer Productivity

See and share on Twitter

Reduce bias in retrospectives with better data

What a data-driven retrospective looks like

How to get started with data-driven retrospectives

A real-life example of holistic hard data

Objectives and key results (OKRs)

Weekly customer report

Sales pipeline

Work Log

Conclusion

4 resources on software team productivity everyone should know

Project Aristotle: Understanding team effectiveness

DORA: Four key performance metrics

SPACE: A framework for developer productivity

Retrospectives: We may be lying to ourselves

Godspeed!

Busting the 10x software engineer myth

What explains productivity differences, if not mere individual talent?

Building a better strategy for achieving business success

TL;DR;

Story of Pixel: How we made an off-the-shelf design system our own

Background

The Goal

Choosing the approach

Making the design system our own

Lessons learned from building on top of a ready-made design system

The pros

The cons

Solutions

Future

How to Disable Server-Side Rendering (SSR) in Next.js

Why Disable SSR in Next.js?

How can you disable SSR in Next.js?

Step 1: Rewrite All Requests to pages/index.js

Step 2: Disable SSR for Page Content

Step 3: Check that Everything Works with npm run dev

Step 4: Build production bundles with next export

Notes on Routing and other Advanced features

Routing

Updating the <title> and Other <head> Tags

Having Multiple Separate Pages

How to Create a ButtonGroup Component with React and Tailwind CSS?

Method 1: PostCSS @apply

Pros 👍

Cons 👎

Method 2: Pseudo-Class Variants with Class Overrides

Pros 👍

Cons 👎

Method 3: Passing Additional Props to Children Using React.cloneElement

Pros 👍

Cons 👎

Method 4: Fully Separate Styles for Button and ButtonGroupButton

Pros 👍

Cons 👎

Conclusion

Step 1: Rewrite All Requests to `pages/index.js`

Step 3: Check that Everything Works with `npm run dev`

Step 4: Build production bundles with `next export`

Updating the `<title>` and Other `<head>` Tags