Alright, let's see your beautifully crafted, corporate-friendly, 15-slide onboarding deck. I'll wait. ✨
Done? Good. Now throw it in the bin. Your new hire's eyes have already glazed over, and they've forgotten what "SSO" stands for.
Instead, here's what actually works for us—a living document, a checklist that assumes nothing and saves everyone's sanity. It’s not about the *what* of the tools, but the *how* and the *why we hate them*. The goal is to get someone from "I have a laptop" to "I pushed a fix" without drowning them in HR-approved fluff.
**Phase 1: The Digital Keys to the Kingdom**
* Access Request: This is a list of every single login they need. Not just "GitHub," but which orgs, which teams, and a link to the internal IT ticket template to request it. We note which ones need 2FA on which device.
* The Sacred `.env` File: Instructions for where to find the *template* for their local environment variables (never the real ones!). The first lesson: "Thou shalt not commit this file."
* SSH Key Ritual: A link to our internal guide for generating and registering a new key. Includes the mandatory, "No, really, use a passphrase" warning.
**Phase 2: The Local Monastery (Setting Up Their Machine)**
* Package Manager Command: One command to install our chosen package manager (brew, apt, etc.).
* The One-Line Install Script: A single script (`./scripts/setup-new-dev`) that installs the runtime, the database, the linter, and the pre-commit hooks. This is the most valuable thing we maintain. It either works, or it breaks loudly and obviously.
* The "Can You See It?" Test: A list of three exact commands. If they can run them all and get the expected output, their base system is blessed.
**Phase 3: The Initiation Rites (First Tasks)**
* Clone, Install, Run: The exact repo, the exact branch, the exact `make` command to start the dev server.
* The "Fake" First PR: A link to a deliberately broken test or a trivial typo in the docs. The task isn't to fix it—it's to navigate the entire flow: branch, fix, commit (with our message format, natch), push, and open a PR. This proves the toolchain works end-to-end.
* The Watercooler Channels: A curated list of the *three* Slack/Discord/Matrix channels that matter for their role. We explicitly list which ones are for help, which are for announcements, and which are for dank memes (crucial).
The philosophy here is simple: automate the obvious, document the tribal knowledge, and treat the process like a codebase—iterative and open to PRs. Every time a new hire gets stuck, the fix gets added to the checklist. It’s ours, it’s free, and it works better than any fancy onboarding platform we’ve ever been forced to use.
Now, let's hear how you do it. Or, more likely, where your process catches fire. 🔥
― Finn
FOSS advocate