39 posts tagged with "guide"

A mid-sized automotive supplier I consulted for in 2024 had a production bug land at 03:15 on a Tuesday. The fix took 8 minutes to code and 19 days to deploy — because it required a software update to PLCs on 14 production cells, each of which could only be updated during the 4-minute changeover window between shift batches. The engineering team's average lead time on the office-IT side: 31 hours. On the shop-floor side: 14 days. Same team, same repository, two different universes of delivery constraint.

Manufacturing software engineering is Agile meeting hardware. The practices that work at a SaaS startup — deploy-whenever, feature flags, canary releases — collide with regulated plant-floor reality: OEE targets, changeover costs, OT/IT separation, and production lines that cannot pause for a deploy. A 2023 Deloitte Smart Factory study found 73% of manufacturers cite "IT/OT integration" as the top barrier to digitization. The problem isn't technology; it's that metrics and rituals designed for pure software break when the software touches a physical process.

Twilio maintains 14 active API versions. Stripe pins every customer to the version active on their signup date and has supported versions going back to 2011. GitHub's REST API runs three major versions in parallel and publishes deprecation headers 12 months before sunset. Your team is probably trying to get away with one — and debating whether the version goes in the URL, a header, or the accept type.

The versioning debate is really three separate decisions stacked into one argument: where the version lives, how breaking changes are scoped, and when old versions die. Getting one right doesn't save you if the other two are wrong. This is a playbook drawn from how the companies that actually run public APIs at scale handle it, plus what we see inside PanDev Metrics customers running internal APIs with 20-200 consumers.

A PropTech team I worked with last year ships 4.2 deploys per week across their flagship product. Their CEO benchmarks that against a reference SaaS portfolio and concludes velocity is "mediocre." It's not. A fintech of similar headcount ships 7.1; a pure B2B SaaS ships 9.4. PropTech lives at the intersection of regulated data, geospatial complexity, and 1990s MLS integrations — the raw deploy-frequency number hides what engineering is actually fighting.

Stack Overflow's 2024 Developer Survey places real-estate software in the bottom third of all industries for reported build and integration-testing speed. Microsoft Research's 2024 DevEx benchmarks show regulated industries losing an average 23% of engineering throughput to compliance friction alone. PropTech layers geospatial complexity on top of that.

A mid-size JavaScript service imports 47 direct dependencies and ends up resolving 2,500+ transitive packages. The same service ported to Go imports 12 direct modules and resolves 42 total. The pip equivalent sits near 180. These are not preferences — they are the shape of each ecosystem, and your dependency strategy has to start from that reality.

Your supply-chain exposure, lockfile discipline, and upgrade cadence should be different in each. This is a playbook for doing that well across npm, pip, and Go modules — the three ecosystems that cover about 84% of production backend code according to the 2025 Stack Overflow Developer Survey.

A team shipping a battery-powered agricultural sensor runs a CI pipeline that takes 38 minutes to build a firmware image, flash it to hardware-in-the-loop, run a 12-minute on-device test suite, and publish artifacts. Their web-app teammates push to main and see green checks in 7 minutes. When both teams get measured on deployment frequency, the firmware team looks like they're underperforming by 5×. They're not. They're doing harder work with a longer feedback loop, and the metric isn't reading it.

Most engineering metrics were built for web software: fast builds, reversible deploys, observability from day one. IoT and embedded teams inherit these metrics and look bad against them. The DORA framework acknowledges this explicitly — the 2023 Accelerate State of DevOps report noted that "teams shipping embedded or regulated software face a different distribution and should not be compared to web teams on deployment frequency alone". This article is what you track instead.

A production release at a 60-engineer SaaS I worked with in 2025 went out at 16:48 on a Friday. The on-call pager fired at 17:22 — a 34-minute latent failure in a feature the release manager had approved "because CI was green." Rollback took 71 minutes because the automation had never been rehearsed with real traffic. Total cost: one customer refund, two engineers' weekends, and a policy change that should've existed from day one.

Release management is the unglamorous half of delivery. DORA's 2024 State of DevOps report ties change failure rate and mean time to restore directly to release discipline — not to engineer talent, not to test coverage. This playbook is the concrete set of rules and rituals that pushed two teams I worked with from monthly pain-releases to daily confident ones.

Google's engineering culture has a ritual: before a line of code ships for anything non-trivial, there's a design doc. Not a 40-page monument — usually 5 to 12 pages, reviewed by two peers, commented in the margins. Researchers at Google's Engineering Practices team have publicly described this as one of the cheapest quality levers the company uses.

Most teams outside Google skip this step or bolt a Confluence template onto an existing process and watch it atrophy. The template below is what actually survives contact with a distracted reviewer at 4:45 PM on a Thursday — the moment most specs live or die.

A 40-person engineering team shipped the same architectural decision twice in eight months — once in June, once in February, reverted both times. The second revert triggered the RFC process. What they discovered reviewing the commit history: the original context had been captured in a Slack thread that auto-archived after 90 days, and the engineer who owned the decision had left. An RFC document would have cost 4 hours to write and saved roughly 3 engineer-weeks of rework.

RFC (Request for Comments) processes exist because technical decisions outlive the people who made them. Stripe, Cloudflare, Oxide Computer, and the Rust project all publish their RFC formats — and the common structure is narrower than most teams assume. This article is the template they converge on, plus a review cadence that works for 10-80 person teams, plus honest numbers on when RFCs waste time.

A team of 60 engineers I worked with last year had 1,400+ Confluence pages, a Notion workspace with 380 pages, a GitHub wiki in each of their 22 repositories, and a "team knowledge" Google Drive. A new hire's second-week task was to find the staging environment runbook. It took her four hours. It existed in all four systems, with three different URLs, two conflicting versions, and one correct but three-year-outdated instruction in the wiki.

This is a comparison of four knowledge-management approaches — Confluence, Notion, GitHub Wiki, and Git-native docs (Obsidian/MkDocs/Docusaurus over a repo) — and a framework for picking one. Microsoft Research's 2024 engineering-productivity report listed "can't find documentation" as the #3 friction point behind slow builds and broken tests, ahead of code review delays. Tool choice is not neutral; it shapes whether documentation gets written, found, and trusted.

A 6-person engineering team running a 15-minute daily standup costs you 7.5 person-hours a week in scheduled time alone. Add context switching cost — UC Irvine's Gloria Mark measured ~23 minutes to refocus after an interruption — and the real cost is closer to 15 hours a week. For a team running 10 weeks on one feature, that's 150 engineering-hours. That's not a meeting. That's a part-time engineer you hired and immediately deployed to talking.

Standups aren't inherently bad. They solve a real problem: surfacing blockers before they rot. The question is whether the daily synchronous format is the only way — or even the best way — to solve it. The State of Agile 2024 report shows 32% of teams actively experimenting with async-first alternatives, and the cleanest data we have from IDE telemetry suggests these alternatives recover 1-2 hours of focus time per developer per week without harming delivery.

This is a comparison of 5 standup alternatives, when each fits, and how to decide which one your team needs.