When a contractor joins a project for a week or a sprint, the onboarding problem isn't the code — it's the context. The code is in the repo. The context is in the heads of the people who've been here a year, and it doesn't transfer in a wiki page.
I've stopped writing wiki onboarding pages. Instead, I hand the contractor a snippet list — a curated set of the commands, configs, and one-liners they'll actually need in the first 48 hours, stored in snippetx and shared as a plain-text export.
This post is about that practice, and why a list of commands is a better onboarding artifact than a document.
Why the wiki page fails
The standard onboarding doc has a structural problem: it's written for the reader who doesn't have the questions yet. It explains the architecture, the conventions, the deploy process — all true, all useful, all in the wrong order. The contractor's first-day questions are concrete and immediate:
- "How do I run the tests?"
- "What's the command to deploy to staging?"
- "How do I get a local database with the right schema?"
- "What's the curl to hit the health endpoint?"
The wiki page answers none of these in a form that's usable at the moment of asking. It has the information, but it's buried in prose, and the contractor is in a terminal, not a browser.
The snippet list answers the questions as commands, in the form they'll actually be typed.
What the list contains
The list is small on purpose — 10-20 entries, each a command or config with a two-word name and a one-line description. The actual entries, from a recent project:
# run-tests
npm test -- --watch
# seed-local-db
npm run db:reset && npm run db:seed
# deploy-staging
npm run build && ./scripts/deploy.sh staging
# health-check
curl -s https://staging.example.com/health | jq .
# tail-api-logs
kubectl logs -f -n prod -l app=api
# reset-migrations
npx prisma migrate reset --force
# create-user
npm run script:create-user -- --email dev@example.com
# clear-cache
rm -rf node_modules/.cache && npm run build
Each entry is a thing they'll do, not a concept they'll learn. The list is a map of the first 48 hours, in the contractor's own working medium (the terminal), in the form they'll use it (copy-paste).
How it's shared
The list lives in a snippetx library on my machine, and the sharing is a plain-text export — no account, no app, no permission dance:
# Export the onboarding list as a file
for id in $(snippetx search onboarding | awk '{print $1}'); do
echo "### $(snippetx show $id | head -1)"
snippetx copy $id
echo
done > onboarding-snippets.txt
The contractor gets onboarding-snippets.txt — a file they can read, grep, and paste from. It's version-controlled in the repo (or sent over chat), it's plain text, and it works on any machine with a terminal. No onboarding SaaS, no shared library account, no "let me get you access."
What changed after I started doing this
1. The first-day questions dropped by half. The questions that remained were the ones a command list can't answer ("why does the deploy script do X?") — the genuinely conceptual ones. The "how do I do Y" questions, which used to be 80% of the first-day interruptions, mostly didn't come, because the answer was in the file.
2. The contractors were productive faster. A contractor who can run the tests and hit the health endpoint in the first hour is a contractor who's in the project by lunch. The time previously spent hunting for commands was time spent reading code.
3. The list improved itself. Every first-day question that wasn't in the list became a new entry. After three contractors, the list had converged on the actual 48-hour workflow, which is more accurate than any wiki page I'd have written from memory.
The meta-point
Onboarding isn't a documentation problem; it's a medium problem. The contractor works in a terminal, so the onboarding should be in a terminal. The wiki page is the right artifact for the conceptual context (the architecture, the why) and the wrong artifact for the operational context (the commands, the how).
The snippet list is the operational half. It's small, it's concrete, it's in the right medium, and it improves itself with every contractor who uses it. The wiki page can keep the concepts. The terminal gets the commands.
npx @wuchunjie/snippetx
More Tools
| Tool | What it does | Command |
|---|---|---|
| scaffoldx-cli | Production-ready project templates in seconds | npx scaffoldx-cli |
| dotguard | Scan .env files for exposed secrets | npx @wuchunjie/dotguard |
| gitpulse | Git repo analytics in your terminal | npx @wuchunjie/gitpulse |
| snippetx | Terminal code snippet manager | npx @wuchunjie/snippetx |
If these save you time, consider buying me a coffee. All tools are MIT-licensed, zero-dependency, and run fully offline.
Top comments (0)