39 posts tagged with "guide"

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 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.

A public company we'll call Company X hit its 2023 engineering DEI target: 28% women in engineering, up from 21%. Two years later, the number was back to 22%. Hiring kept working; retention didn't. The post-mortem found three patterns the original program missed: under-promotion of women with 2-4 years tenure, above-average code-review rejection rates for under-represented minorities, and assignment bias toward "glue work" that doesn't count for promotion.

Most engineering DEI programs stop measuring at the top of the funnel. Hiring numbers are public, easy to collect, and lend themselves to targets. What happens after someone joins — the promotion rate, the review cycle, the assignment pattern — is where culture actually lives. And it's where programs succeed or fail quietly, often without management noticing until the exit interviews pile up.

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.

GitHub's 2024 internal research on Copilot Chat found developers accept LLM-generated fixes in roughly 31% of debugging sessions — but only 11% of those fixes actually closed the underlying bug. The other 20% patched a symptom, introduced a regression, or confidently pointed at the wrong subsystem. An ACM 2024 study from Shi et al. on LLM-assisted debugging across 2,500 sessions reported a similar pattern: speed-up happens on shallow bugs; deep bugs often get worse when the developer outsources hypothesis generation.

The takeaway is not "don't use LLMs to debug." It's: use them where they're measurably better, skip them where they systematically lie, and build a workflow around the difference. This post walks five workflows that actually save time, drawn from instrumenting our own team and five PanDev Metrics customer teams.