46 lines
1.5 KiB
Markdown
46 lines
1.5 KiB
Markdown
|
# 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.
|