1.5 KiB
1.5 KiB
Onboarding Documentation
Purpose
Help new contributors or users become productive quickly by reducing ambiguity, setup friction, and missing context.
When to use
- Improving setup or first-run guidance
- Writing contributor onboarding docs
- Creating "start here" guides for internal or external users
- Simplifying confusing developer or product entry points
Inputs to gather
- Current setup steps and prerequisites
- Common failure points, hidden assumptions, and missing context
- Existing onboarding flow and repository conventions
- Intended audience: contributor, operator, customer, or teammate
How to work
- Optimize for first success, not exhaustiveness.
- Put prerequisites, setup order, and validation steps in the order a new person needs them.
- Surface gotchas early rather than burying them after failures occur.
- Use concrete commands, examples, and expected outcomes when they reduce confusion.
- Trim insider jargon unless it is explained.
Output expectations
- A cleaner onboarding path with clear first steps
- Documentation that reduces setup ambiguity and dead ends
- Helpful validation or troubleshooting guidance where needed
Quality checklist
- A new person can tell where to start.
- Steps are ordered logically and are easy to verify.
- Prerequisites and common failures are not hidden.
- The doc avoids assuming too much existing context.
Handoff notes
- Note any setup steps you could not verify directly.
- Pair with technical docs when onboarding depends on deeper conceptual explanation.