Documentation-first onboarding: Why your new hires shouldn't need to ask basic questions

General
1

Controversial take: If new hires are constantly asking basic questions, your documentation failed, not them.

At Uber’s mobile platform team, we serve thousands of engineers across São Paulo, San Francisco, Amsterdam, Bangalore, and more. We don’t have the luxury of hallway conversations. Everything has to work async-first.

Here’s what we learned: The quality of your documentation directly predicts your onboarding speed.

The Mindset Shift: From “Just Ask” to “Docs First, Then Ask”

Old culture: “Don’t waste time documenting, just ask in Slack.”
New culture: “Document it once, reference it forever.”

The math is simple:

  • Writing a doc takes 30-60 minutes
  • Answering the same question 20 times takes 10-20 hours
  • Plus: Every interruption breaks flow for the person answering

What We Document (And How)

1. Architecture Decision Records (ADRs) with Video Walkthroughs

Every major technical decision gets:

  • Written ADR (why we chose X over Y, tradeoffs, context)
  • 15-minute video walkthrough by the engineer who made the decision
  • Code pointers to see it in action

Example: Why we chose React Native over native for certain features. The ADR explains the decision. The video shows a senior engineer walking through a real implementation.

New hires can watch at 1.5x speed on their own time. No need to schedule time with a busy principal engineer.

2. Troubleshooting Playbooks

Common setup issues documented with:

  • Symptoms: “When you see error X…”
  • Root cause: “This happens because…”
  • Solution: Step-by-step fix
  • Prevention: How to avoid it next time

Example playbook: “iOS build fails with ‘Pods not found’”

  • 8-step fix with screenshots
  • Link to why our Podfile is structured this way
  • Common variations of the error

Result: 60% reduction in setup-related questions in Slack.

3. “Day in the Life” Videos

Different roles (iOS engineer, Android engineer, mobile platform engineer) record their typical workflows:

  • Morning routine (checking dashboards, reading alerts)
  • How they approach a new feature
  • Their code review process
  • How they test changes

These videos are gold. New hires see how senior engineers think, not just what they produce.

4. Code Navigation Guides

“Start here” docs for each major system:

  • Entry point: Which file/class to look at first
  • Core concepts: 3-5 key abstractions to understand
  • Common flows: Typical user journey through the code
  • Where to add new features: Specific guidance

Instead of “go read the codebase,” we give a guided tour.

The Results

After shifting to documentation-first:

  • 60% reduction in onboarding-related Slack questions
  • 40% faster time to first PR (from 3 weeks to 1.8 weeks average)
  • Unexpected benefit: Existing engineers use the docs when context-switching between systems

The documentation culture made our codebase more maintainable for everyone, not just new hires.

The Maintenance Challenge

The honest problem: Docs get stale.

Video recorded 6 months ago shows old UI. ADR references architecture we’ve since changed. Playbook doesn’t cover new setup steps.

Our solution (imperfect but working):

  • Doc ownership rotation: Each engineer owns a section of docs for a quarter
  • New hire feedback loop: Every new hire’s first task is to file issues on confusing/outdated docs
  • No PR merged without doc update: Automated check that fails PR if relevant docs aren’t updated

It’s not perfect. Some docs still drift. But it’s way better than no docs.

The Culture Shift Required

This only works if you change incentives:

Before:

  • Speed = heroism (“I jumped on a call and unblocked them!”)
  • Documentation = nice-to-have

After:

  • Writing docs = force multiplication (you just unblocked future you and 50 other people)
  • Answering the same question twice = technical debt

We made documentation quality part of performance reviews. Sounds harsh, but it works. Senior engineers now want to create great docs because it’s how they demonstrate impact at scale.

My Challenge to You

Stop blaming new hires for asking questions. Start asking: Why didn’t our documentation answer this?

Track every question in your onboarding Slack channel for a month. Categorize them. Then document the top 20.

I guarantee your next cohort ramps 30% faster.

Questions for the Group

How do you handle video documentation becoming outdated? We re-record quarterly, but it’s time-consuming.

What tools actually work? We use Notion for text docs, Loom for videos, and GitHub for ADRs. Considering centralizing but haven’t found the perfect tool.

How do you incentivize documentation without it feeling like homework? Making it part of perf reviews helped, but curious what else works.

2

This is the future. Async-first documentation is equity for distributed teams.

When knowledge lives in people’s heads or in “just ask” culture, you create two classes of employees:

  1. Those in the right timezone / office who can tap people on the shoulder
  2. Those who have to wait 12 hours for an answer

Documentation levels the playing field.

We implemented a similar approach at our EdTech startup:

Created a documentation rotation where each engineer owns an area of docs for a quarter:

  • Infrastructure docs owned by Platform team
  • Mobile docs owned by Mobile team
  • Backend API docs owned by Backend team

Ownership means:

  • Keeping docs current
  • Responding to doc issues within 48 hours
  • Quarterly review and refresh

Made doc quality part of performance reviews (your approach). This was controversial at first. Engineers pushed back: “We’re paid to write code, not docs.”

Response: “You’re paid to create leverage. Code + docs = sustainable leverage. Code alone = firefighting.”

It took 6 months to shift the culture, but it worked.

My question: How do you handle video documentation becoming outdated?

Videos are powerful but expensive to maintain. We tried quarterly re-recording and it became a burden.

New experiment: “Living” videos with timestamp annotations.

  • Pin a comment with timestamps: “0:00-3:00 still accurate, 3:00-5:30 outdated (see new doc), 5:30+ still relevant”
  • Update annotations instead of re-recording entire videos
  • Only re-record when >50% is outdated

Too early to say if this works, but it’s less overhead than full re-records.

3

Love this approach, but I’m facing cultural resistance from old-guard engineers in financial services.

The pushback I hear:

  • “We don’t have time to document”
  • “The code should be self-documenting”
  • “This is bureaucratic overhead”

But here’s the irony: These same engineers spend 5-10 hours a week answering the same questions from new hires.

What worked to shift the culture:

1. Made it a PR requirement: No PR approved without updating relevant docs.

Our CI pipeline has an automated check:

  • If you touch files in /auth, did you update auth docs?
  • If you add a new API endpoint, did you update API catalog?

This felt heavy-handed at first, but it made documentation part of the workflow instead of an afterthought.

2. Showed the ROI in engineer time:

I tracked hours spent answering onboarding questions for 2 months:

  • Senior engineers: 8 hours/week on average
  • Mid-level engineers: 4 hours/week

After we built the doc library:

  • Senior engineers: 2 hours/week
  • Mid-level engineers: 1 hour/week

That’s 6 hours/week per senior engineer freed up for actual work. At our fully-loaded cost, that’s ~$25K/year per senior engineer in reclaimed time.

Showed this to leadership. Suddenly documentation became a priority.

My question: How do you handle knowledge that’s genuinely hard to document?

Some things really are tacit knowledge—judgment calls, intuition built over years.

Example: “How do we decide when to refactor vs. ship with tech debt?”

This isn’t a checklist. It’s experience and context. How do you document that without creating rigid rules that miss nuance?

4

Product perspective: We desperately need this but struggle with tooling.

Our problem isn’t lack of documentation. It’s documentation chaos.

Product requirements might live in:

  • Notion (product specs)
  • Google Docs (strategy docs)
  • Jira (user stories)
  • Figma (design specs with comments)
  • Slack (decisions made in #product-chat)
  • Email (stakeholder feedback)
  • Confluence (old wiki that nobody maintains)

New PMs spend their first month just finding information. It’s exhausting.

Question: What tools actually work?

We’ve tried:

  • Notion: Great for writing, terrible for search
  • Confluence: Powerful but cluttered, people stop maintaining it
  • GitHub wiki: Engineers like it, but non-technical folks won’t use it
  • Google Docs: Easy but turns into a graveyard of orphaned docs

The mobile team uses Notion + Loom + GitHub. But how do you convince non-engineers to adopt GitHub?

The real problem might be organizational, not technical:

Maybe the issue isn’t which tool, but that we don’t enforce a single source of truth.

Every team picks their own tool. Then we wonder why onboarding is chaotic.

Should there be a company-wide mandate: “All product specs in X, all technical docs in Y, all videos in Z”?

Or is flexibility worth the coordination cost?