Knowledge Sharing and Team Enablement Questions

Direct answer

I treat the new senior engineer as both a learner and the best available documentation tester. They arrive with fresh eyes, so every confusion they hit is a gap in our onboarding. I get them productive through a real small task with a guide, and I make writing down what they learn part of the job, so the second newcomer has it easier than the first.

Plan

1. Before day 1 (me). Working laptop and access, a named buddy, and a first real ticket that is small, valuable and touches the main flow. Do not wait for docs to exist.
2. Week 1: guided map. Two or three sessions with long-tenured engineers, recorded: the request path through the system, the deploy process, and "where the bodies are buried" (the fragile areas and odd conventions that only long-tenured people know). Use a simple C4-style picture (C4 is a way of drawing a system at increasing zoom levels: context, containers, components, and a fourth level, code, which teams rarely draw by hand; the first three are enough for onboarding), even hand-sketched, as the anchor. For a typical web product: context = users and the outside systems (payments, email) around our system; containers = web app, API, database, job queue; components = inside the API, the auth, orders and billing modules.
3. Weeks 1 to 2: ship something. Pair on the ticket and get it to production. Nothing teaches a codebase like one real change end to end.
4. Onboarding log. The newcomer keeps a running list of every question they had to ask and every surprise. Example log lines: "Day 2: how do I get a test database? (asked buddy)"; "Day 4: why are there two config files? (surprise)"; "Day 9: who approves a deploy? (asked three people)". Each week, the top items become docs: a setup script, a "how a request flows" page (one diagram plus a numbered list: browser, load balancer, API, database, and what can fail at each hop), a known-gotchas list. Rule: the answer goes into the doc within a day, where the next person would look.
5. Owner. One named person keeps the onboarding doc alive, and the newcomer's first onboarding retrospective at day 30 (a short meeting on what worked and what was missing in their first month) updates it.

Worked example (illustrative)

Day 3: newcomer spends four hours getting local setup working because two steps live only in a colleague's head. That becomes a single setup script by day 5. Week 3: the log shows five questions about the deploy process; those become a one-page runbook (step-by-step instructions for one task, here how to deploy). Measure: days to first merged change and first production deploy for this hire, compared with the next hire, and whether hire two needed fewer questions.

Pitfalls

• Asking a senior person to "just read the code" for a week; they become slow and disengaged.
• Documenting everything at once. Follow real questions; docs nobody asked for go stale.
• Making the newcomer the sole writer with no time budget. Give it explicit time and a reviewer.

Direct answer

I would run office hours (a recurring slot where anyone can drop in with questions) as a lightweight service: a small number of fixed slots that cover the time zones, a simple intake form so questions can be triaged, a shared log of questions and outcomes, and a habit of turning repeated questions into docs. I would judge success by whether people get unblocked faster and whether the same questions stop coming back.

Setup

• Slots and time zones. Two recurring slots: one in the overlap of Europe and the Americas, one for Asia-Pacific, each 45 minutes, with different hosts. For teams too spread out, add an asynchronous channel where questions are answered within a stated window (for example, one business day).
• Drop-in versus appointment. Drop-in by default, since most questions are short. Offer a bookable 25-minute slot for deep problems such as reviewing a data model or a reliability design.
• Triage. A short form asks: what are you trying to do, what have you tried, how urgent. Urgent production issues go to the on-call path, not office hours.
• Hosts. Rotate among team members so knowledge spreads and nobody is a permanent help desk.
• Advertising and the first sessions. Announce in team channels and at onboarding, and seed the first sessions with a known pain (invite a team with a real question) so it does not open to an empty room.
• Capture. Log each question: date, topic, who, outcome, and whether a doc exists.

How I would know it helps

• Repeat rate: the share of questions on topics already answered before.
• Docs created from questions, and whether questions on a documented topic fall afterwards.
• Time to unblock, reported by attendees in one line.
• Attendance mix (new people, several teams) and a short satisfaction check.

Worked example (illustrative log)

Over 3 weeks the log has 30 questions. One topic, "how to request a new data pipeline environment", accounts for 9. That is 9/30 = 30%. I write a one-page guide and link it in the intake form. In week 4, that topic is 2 of 14 questions, about 14%, and people who asked it say the guide answered it. The metric shows that the office hours found the gap and the doc closed it. If the share had not fallen, the guide is unclear or not discoverable.

Trade-offs and pitfalls

• Office hours can become a substitute for documentation. The goal is to shrink repeated questions.
• Low attendance may mean poor advertising, the wrong time, or that people are already served, so ask before cancelling.
• Do not use raw attendance as the success measure, since a good doc reduces attendance.

Direct answer

Knowledge sharing is how what one person knows becomes usable by others on the team; knowledge transfer is the deliberate version, moving a specific body of knowledge from someone to someone (for example, when an owner changes). The useful distinction is between explicit knowledge (can be written down and looked up) and tacit knowledge (know-how gained by doing, hard to write down). Teams need both, and they move through different practices.

Explicit versus tacit

Practices you should expect to see working

• Docs live next to the work: updated in the same pull request (proposed code change) as the code, each with an owner and a last-reviewed date.
• Code review that explains the why, not only "change this".
• Blameless postmortems (incident reviews that examine causes, not culprits) that produce written actions.
• On-call shadowing and rotations so more than one person has handled each system.
• Regular demos, brown-bags (informal lunchtime talks) and office hours (a fixed slot where anyone can ask an expert questions).

Team flavours:

• Backend microservice team: each service has an owner, an ADR trail, an API contract document (a written spec of what the service accepts and returns), and a shadow on the on-call rota (the rotating schedule of who responds to alerts).
• SRE (site reliability engineering) team: runbooks tested during game days (rehearsed failures), handoff notes at every on-call shift change, postmortem review meetings.
• BI (business intelligence) team: recorded dashboard walkthroughs, a shared glossary of metric definitions, weekly office hours for the people who read the dashboards.

Worked example: first 90 days after a launch

A silo is an area only one person understands, so if they leave or are unavailable the work stalls. The day-90 silo review lists each area of the system and counts who could handle it alone; any area with one name gets a pairing plan, for example two more people take turns as second pair of hands.

Trade-offs and pitfalls

• Over-relying on documents for tacit knowledge produces a large, stale wiki; over-relying on conversation produces a team that cannot survive turnover.
• Sharing that depends on goodwill alone fades under deadlines; give it calendar time and owners.
• Count sharing by outcomes (fewer repeated questions, more people able to handle an area), not by attendance.

Direct answer

I would run a structured two-week programme with four controls: least-privilege access (only the permissions their task needs, for a limited time), a short essential reading list, paired then supervised work, and a documentation handover with acceptance criteria before they leave. That protects quality and access up front and makes the knowledge stay with us as an explicit deliverable, not a hope.

Before day 1: scope and access

• Define the outcome and the systems they need, nothing more. Agree confidentiality terms and code-ownership in the contract (the company owns the code and documents produced, and the work lives in our repositories, not theirs).
• Provision access with the minimum role, time-boxed to the end date, non-production first. No shared accounts; use named accounts so actions are auditable (every action can be traced to one person). Production write access only if the task truly needs it, and then only through a reviewed change.
• Name an internal sponsor (owns the relationship) and a buddy (answers day-to-day questions).

Two-week plan

Days are working days: two weeks = days 1 to 10.

Handover and acceptance (the part that keeps the knowledge)

The contractor's deliverable includes documentation, and payment or sign-off depends on it. For a software contractor: a runbook (step-by-step instructions to deploy, operate and fix the system), decisions made and why, and how to run and test it. For an analytics consultant: the data models, query logic, metric definitions and dashboard notes. Acceptance criteria (written before the work starts): (1) a person outside the project can set up and run it in under half a day using only the docs; (2) every decision with real alternatives has a written reason; (3) all metric definitions or config values are listed; (4) tests or checks pass and are documented. Acceptance test: an internal person follows the documentation cold and reproduces the result. Then a 30-minute recorded walkthrough, and access is revoked with a checklist (accounts, keys, repositories, shared channels), for example: [ ] named account disabled [ ] API keys rotated [ ] removed from repos and chat channels [ ] laptop or VPN access ended [ ] confirmation sent to the sponsor.

Worked example (illustrative)

A consultant builds a reporting dashboard. Day 1 access: read-only to one warehouse schema (a named group of tables in our data warehouse), valid until day 10, the end of the engagement. Day 10: our analyst rebuilds the top three charts from the consultant's notes alone; two steps are missing, consultant fixes them, we accept and revoke.

Trade-offs and pitfalls

• Too little access and they stall; too much and one mistake reaches production. Start narrow and widen on request with a reason.
• Documentation promised "at the end" is the first thing dropped. Make it a milestone at day 8, not on the last day.
• Do not let knowledge sit only in the contractor's head or personal notes.

Direct answer

Rank services by two things multiplied together: how much the business would hurt if the service stayed broken (criticality) and how few people could actually fix it (concentration). Concentration is the "bus factor" idea: the number of people who could disappear (leave, get sick, go on holiday) before nobody left can safely change or restore the system. I would collect cheap, objective signals from version control, the incident record and the docs, sanity-check the top of the list with a direct question to the team, and then spend my limited effort only on the top few.

Signals to use

Plain-language notes on the caveats: a squash merge combines a whole branch into one commit credited to whoever merges it; a pair commit credits one author although two people worked on it; a drive-by fix is a one-off small edit by someone who does not otherwise work on the service; paged means the alert reached that person's phone as the on-call responder; a tier list is the team's agreed ranking of services by importance (for example, tier 1 = payments, sign-in). Without an agreed tier list, ask the team to rank the services once before scoring.

# Commits per author for one service over the last 12 months
git shortlog -sn --no-merges --since="12 months ago" -- services/payments-ledger/
# Who last touched it, newest first
git log --no-merges --format='%an %ad' --date=short -- services/payments-ledger/ | head -n 20

What the flags do: -s prints only a summary count per author, -n sorts by count (highest first), --no-merges skips merge commits, --since limits the time window, and everything after -- restricts the search to that directory. head -n 20 keeps the first 20 lines. Illustrative output of the first command for payments-ledger (240 commits in total):

   204  Priya Nair
    36  Tom Weber

204 / 240 = 85 percent top share, and 2 distinct authors, which are the two numbers in the worked example below.

Scoring rule

Concentration score (0 to 3), one point each: top author has 60% or more of commits; fewer than 3 active contributors; no runbook that is current (a runbook counts as current if it was edited in the last six months or someone other than its author has followed it successfully; otherwise it is stale). Criticality: tier 1 = 3, tier 2 = 2, tier 3 = 1.

risk = criticality x concentration

The rule is deliberately crude: it is a triage list, not a measurement. It scores only the three signals that come straight from version control and the docs, because they are cheap to compute for every service. Commit staleness and incident involvement take manual digging, so I use them afterwards to check the top of the list and to break ties, not to score every service.

Worked example (illustrative services and numbers)

Ranking: payments-ledger (9), search-indexer (6), admin-ui (3), report-exporter (2), notifications (0). I would treat the first two now. Note that notifications is tier 1 yet last, because many people already know it, and admin-ui is fully concentrated but low stakes, so it can wait.

Validate and act

• Ask the top five "who could restore this alone at 3 a.m.?" The git data suggests candidates, the answer is the truth.
• Tie-break equal scores by pages per quarter: the service that actually breaks needs knowledge sooner.
• Treatment is proportional: runbook plus a second on-call for the top two, a lighter pairing plan for the rest, and an explicit decision to accept the tail.

Trade-offs and pitfalls

• Commit counts measure typing, not understanding; the incident record measures operating. Prefer both.
• Signals get gamed (splitting commits, one-line edits to fake contributors), so keep them as triage inputs rather than performance targets.
• A monorepo (one repository holding many services) or generated code (files written by a tool rather than a person) inflates one author; exclude generated paths.
• I would flip the ranking for a fast-approaching departure or leave: a known exit date raises that person's services above everything.