Why this matters
Backend systems live longer than teams. Good knowledge sharing and onboarding reduce time-to-impact for new engineers, prevent incidents, and make handovers smooth. In practice, you will:
- Onboard teammates to a service: from local setup to safe production changes.
- Run knowledge-sharing sessions about architectures, incidents, and design decisions.
- Hand over ownership during rotations or when leaving a team.
- Keep a living knowledge base that is easy to find, trust, and update.
Concept explained simply
Knowledge sharing means turning what’s in people’s heads into small, findable artifacts that others can use without you. Onboarding is the guided path that turns a newcomer into a safe, productive teammate.
Mental model: The Knowledge Flywheel
- Capture: Write the minimum needed to unblock others.
- Share: Demo, pair, or present briefly.
- Apply: Let others try with small, safe tasks.
- Improve: Update docs after real use.
Repeat this cycle for every critical service or process.
Core components
- Single-source Starter: A 1-page service onboarding guide with links to deeper docs.
- Runbooks: Step-by-step actions for common tasks (deploy, rollback, restart, on-call basics).
- System Map: What depends on what, and who owns it.
- Learning Path: 1–2 weeks of tasks that escalate responsibility safely.
- Sharing Rhythm: Short, regular sessions (15–30 min) with a repeatable format.
Worked examples
Example 1 — 1‑page service onboarding guide
Goal: Get a new engineer to run and deploy the service safely.
Title: Orders Service — Onboarding (1 page) Owners: @orders-team (Slack: #orders) What it does: Manages order lifecycle and payments handoff Critical dependencies: Postgres (orders-db), Payment API, Kafka (orders-events) Local setup (≈20 min): prerequisites, env vars, start command, health check URL Deploy & rollback: pipeline name, how to promote, how to rollback Runbook: common ops (restart worker, reprocess dead letter queue) First 3 tasks: (1) Run tests locally (2) Add a health endpoint log (3) Do a canary deploy Safety notes: feature flag for risky code; do not modify migration history
Example 2 — Knowledge-sharing session plan (30 min)
Topic: How our retry and idempotency work in the Payment flow.
Outcome: Attendees can explain idempotency keys and change a retry policy safely Agenda: 0–5: Problem & impact (2 incidents we had) 5–12: Architecture walkthrough (diagram + key code paths) 12–20: Live demo (change retry from 3 to 5 in staging) 20–25: Q&A + gotchas 25–30: Mini-task: attendees outline a safe rollout checklist Artifacts: slide with diagram, link to runbook, example PR
Example 3 — Handover checklist for on-call rotation
Handover Pack - Current risks: delayed Kafka consumer; patch pending - Dashboards to watch: orders lag, payment error rate - Pages to read: incident #142 summary; rollback runbook - Who to call: SRE primary for Kafka; Payments SME - Test alarm: simulate a warning to verify pager integration - Backlog: top 3 issues and why they matter
Example 4 — First 2 weeks onboarding tasks (safe escalation)
Week 1: read 1-pager, run service, make non-prod change, shadow deploy, fix a low-risk bug Week 2: own a small feature behind a flag, write/update runbook step, present a 5-min demo
How to do it (step-by-step)
- Pick one critical service. Timebox 60 minutes.
- Create the 1‑page onboarding guide (owners, purpose, setup, runbook, deploy/rollback, first tasks, safety notes).
- Identify top 3 runbooks to maintain (deploy, rollback, restart/scale).
- Define a 2‑week onboarding path with small, verifiable tasks.
- Schedule a 15–30 min share-out: problem, architecture, demo, Q&A.
- After first use, ask the newcomer to improve the docs (flywheel: improve).
Checklists
Onboarding pack readiness
- Clear owners and support channel listed
- Local setup reproducible in under 30 minutes
- Deploy and rollback steps verified this month
- Runbooks exist for top 3 operations
- First 3 tasks defined and safe
- Known risks and contact map included
Knowledge-sharing session quality
- States expected outcome in one sentence
- Has a small live demo or recorded clip
- Includes one mini-task to apply learning
- Leaves behind an artifact (slides/notes/runbook link)
Handover completeness
- Risks, dashboards, and runbooks are linked
- Escalation contacts are explicit
- A test alarm or dry-run was performed
- Top backlog items explain impact, not just titles
Exercises
Complete these to cement the skill. The quick test is available to everyone; only logged-in users get saved progress.
Exercise 1 (ex1) — Draft a 1‑page service onboarding guide
Pick any backend service you know. Create a 1‑page onboarding guide including: purpose, owners, local setup, deploy/rollback, critical dependencies, runbook basics, first 3 tasks, safety notes.
Timebox: 45 minutes. Aim for clarity over completeness.
Template
Service name — Onboarding (1 page) Owners: What it does: Critical dependencies: Local setup (≤30 min): Deploy & rollback: Runbook basics: First 3 tasks: Safety notes:
- Success: a newcomer can run tests locally and describe a safe deploy.
Exercise 2 (ex2) — Plan a 30‑minute knowledge-sharing session
Choose a topic (e.g., a queue consumer or caching strategy). Define outcome, audience, 30‑min agenda, simple demo, and a mini-task.
Template
Topic: Outcome (one sentence): Audience: Agenda (0–30 min): Demo plan: Mini-task: Artifacts to keep:
- Success: attendees can perform one safe change without help.
Common mistakes and self-check
- Writing encyclopedias: If it doesn’t fit a page, start with a page and link deeper docs later.
- Skipping rollback docs: Practice rollback monthly and update the steps.
- Unclear ownership: Every doc must show current owners and support channel.
- Outdated setup: Re-run setup quarterly; time how long it takes.
- No application: Sessions without a demo or mini-task don’t stick.
Self-check prompts
- Can a new hire ship a tiny, safe change in week 1?
- When was rollback last verified?
- Do runbooks name who to call at 2am?
- Do newcomers suggest doc fixes after first use?
Practical projects
- Service Starter Kit: Turn your 1‑page guide into a reusable template for all services. Acceptance: at least 2 other services adopt it.
- Rollback Drill: Schedule and run a non-prod rollback drill; update runbook with real timings. Acceptance: steps are accurate and timeboxed.
- Incident Teach-Back: Summarize a past incident in 5 minutes with 3 takeaways and an updated runbook step. Acceptance: peers can repeat the fix.
Learning path
- Draft the 1‑page onboarding guide for one service.
- Create/refresh deploy and rollback runbooks; verify them.
- Run one 30‑min knowledge-sharing session with a demo.
- Define a 2‑week onboarding task list; have a newcomer try it.
- Iterate based on feedback; keep improving the flywheel.
Who this is for
- Backend Engineers who want faster team ramp-up and safer operations.
- Tech Leads responsible for onboarding and service ownership.
- SREs standardizing runbooks and incident learning.
Prerequisites
- Basic Git and code review workflow.
- Ability to run a service locally and read logs.
- Familiarity with your team’s CI/CD pipeline.
Next steps
- Finish Exercises 1–2.
- Run one knowledge-sharing session this week.
- Take the Quick Test to validate your understanding.
Mini challenge (20 minutes)
Find one gap in your current onboarding. Fix it now. Example: add a rollback step, clarify owners, or time the local setup and remove one hurdle.
Progress saving note
The quick test is available to everyone; only logged-in users get saved progress.