43 posts tagged with "tutorial"

A senior engineer at a fintech client spent 3.5 hours writing a runbook for a deploy process she hoped no one would ever run manually. Eight months later, it saved a junior on-call engineer roughly 4 hours at 2 a.m. on a bank holiday. That doc produced a tidy 15% time return. A peer doc written the same week — a 6-page architectural overview of a system being deprecated — has never been opened by anyone, according to the wiki logs. Same team, same hours, wildly different ROI.

Documentation is not free, and it is not infinitely valuable. The engineering conversation is usually framed as "we need more docs" or "docs are always stale" — both true at once, which is the clue. The actual question is: which docs pay back, how fast, and when writing them is worse than admitting the knowledge is tacit. This is a framework for making that call before committing the hours.

Engineers lose an average of 11.5 hours per week to meetings and the refocus penalty that follows them. UC Irvine's Gloria Mark (the 23-minute refocus study, updated 2023) now puts the post-interruption cost for knowledge workers at 23 minutes and 15 seconds per context switch. Four meetings a day is literally three hours of lost focus time on top of the meetings themselves. Your Google Calendar tells you 6 hours; the real cost is closer to 9.

This is a playbook for cutting meeting load in half on an engineering team without losing the alignment that the meetings were (theoretically) providing. It's async-first, not async-only — some meetings are still the right tool, and pretending otherwise is how async cultures themselves fail.

A VP of Engineering told me the number that hurts: "We spent $140,000 on an offsite in Bali in Q1. By Q3, nobody on the team remembered a single decision we made there." A 40-person engineering offsite routinely costs $80-200K in direct spend (travel, venue, food, activities) plus 200-320 engineer-weeks of displaced work, and the Gallup 2023 Workplace Report documents that only 29% of companies can articulate a measurable outcome from their last off-site event.

The default failure isn't venue or agenda — it's that the offsite was scheduled as a cultural ritual with outcomes defined after the fact. Flipping that order changes the ROI by an order of magnitude. The framework below is how the engineering leaders with repeatable-ROI offsites plan them, and it works across the three formats that produce measurable results: hackathons, strategy sprints, and team-bonding events. Each format has different economics.

A Microsoft Research 2024 study of 31,000 knowledge workers' calendars found the median engineer at a 200-500-person software company sits in 23 hours of scheduled meetings per week. UC Irvine's Gloria Mark — the researcher who gave us the 23-minute refocus number — has said that a typical knowledge worker gets interrupted every 3 minutes and 5 seconds once meetings end and Slack begins. Add the 40-minute commute many have quietly added back in 2026, and a coding day starts at 11am.

Most "calendar hygiene" advice is either throwaway ("just say no to meetings") or religiously rigid ("maker time MWF only, you can do nothing else"). Neither survives contact with a real engineering organization where your feature depends on another team's design review. This is the template that does.

Your team-building offsite is on the calendar. Historically, trust falls and escape rooms land at 1.8/10 on the "would do again" question. Internal hackathons rate 8.4/10, bug-bash days 7.1/10, lunch-and-learns 6.8/10. These numbers come from a 2-year rating survey we ran across 23 engineering teams (327 engineers total) alongside our IDE dataset. The pattern is blunt: engineers rate activities that are adjacent to their work much higher than activities that deliberately aren't. Google's Project Aristotle found psychological safety is the strongest predictor of team effectiveness, and the activities that build it are not the ones HR usually picks.

This article walks through which team activities correlate with actual team health signals (retention, voluntary collaboration, PR-review engagement) and which ones correlate with nothing except spend. You'll leave with a ranked shortlist and a few guardrails on what to skip.

Every engineering org has tried the kudos bot. Most are dead within 9 months. A 2024 Gallup meta-analysis of 1.2M workers flagged something specific about technical roles: peer recognition drives 2.7× higher engagement lift than manager praise for engineers, but only when the recognition meets three criteria — specific behavior, public visibility, and timely delivery. The average Slack /kudos command meets none of them.

This is a playbook for a peer-recognition system that actually keeps running past year one. It works for teams of 10-200, costs under $50/engineer/year, and — contrary to most vendor decks — has nothing to do with points or badges.

Two senior engineers at a 60-person SaaS I mentored stopped speaking for seven weeks. The cause, by their accounts, was "a personality clash." The cause, by the data: engineer A had merged without review into engineer B's service 23 times in 8 weeks; engineer B's review queue had grown from 4 PRs to 31 in the same window. Each had a legitimate grievance neither could cleanly articulate. The moment their EM put the two numbers on a slide, the fight ended — not because anyone won, but because the dispute stopped being about the other person's character.

Most conflict in engineering teams isn't about personalities. It's about process gaps, priority mismatches, and workload inequities that people can't see from inside the conflict. A 2022 Harvard Business Review study on team dysfunction placed "ambiguity about who owns what" as the #1 driver of interpersonal conflict on knowledge-work teams. The resolution isn't better feelings — it's a shared picture of reality. Data is how you build it.

Netflix's "Freedom & Responsibility" deck was downloaded more than 20 million times after Patty McCord published it in 2009. Stripe's engineering principles, GitLab's Handbook, Basecamp's Shape Up — the public culture documents that became landmarks share three properties: they're short, they're opinionated, and they describe how decisions get made, not what the team values in the abstract.

Most engineering-culture docs written at most companies die within a year. They die because they're written for an offsite, printed on a poster, and never referenced again when the real test comes: a conflict between shipping speed and code quality at 5:30 PM on a Thursday. This post gives a template that survives that moment, with three filled examples drawn from real engineering organizations.

Tom Preston-Werner published "Readme Driven Development" in 2010, and most engineering teams read it, nodded, and continued writing the code first. Fifteen years later, the teams in our dataset that actually practice RDD ship 22% fewer rewrites in the first 90 days of a new service and onboard new engineers to that service 3× faster than teams that write documentation after the code lands. The gap isn't about documentation quality. It's about what writing forces you to think through.

RDD is a working practice: write a credible README for the thing you're about to build, get it reviewed, then write the code. This article explains what changes for teams that adopt it, the measurable difference across 28 RDD-practicing teams we track, and honest limits on where it helps and where it's theater.

Most engineering teams in 2026 have three distinct kinds of prompt users on the same payroll. There's the power user who has a 60-line Cursor rules file honed over 6 months. There's the casual user who copy-pastes "fix this bug please" and is happy enough. And there's the skeptical user who tried it twice, got bad results, and concluded AI-assisted coding is overhyped. Your team's AI productivity is dragged to the average of those three, not the top.

Individual prompt skill is a personal productivity hack. Team prompt engineering is a process — and most teams haven't treated it as one yet. We'll lay out a playbook for codifying prompts across the team, including what to share, what to keep individual, the metrics that tell you it's working, and the specific failure modes we've seen inside our customers.