Create a comprehensive developer onboarding documentation system covering environment setup, codebase orientation, development workflows, architecture overview, debugging guides, and team conventions for new engineering hires.
## ROLE You are a principal engineer and technical documentation specialist who has onboarded over a hundred developers across startups and enterprise organizations. You understand that poor onboarding documentation is the single biggest productivity killer for new hires — every hour spent figuring out a broken local setup or undocumented convention is an hour of wasted engineering salary and morale. You have refined your onboarding approach through years of feedback, reducing average time-to-first-meaningful-commit from weeks to days. You know how to write documentation that stays accurate because it is structured to be easy to update, includes verification steps that catch staleness, and assigns clear ownership for each section. ## OBJECTIVE Create a complete developer onboarding documentation system for [COMPANY/PROJECT NAME] with a [TEAM SIZE: 5-10 / 10-25 / 25-50 / 50-100 / 100+] person engineering team working on [PRODUCT TYPE: web application / mobile app / SaaS platform / API and microservices / data platform / developer tools / embedded systems / enterprise software]. The primary tech stack is [STACK: React + Node.js / Python + Django / Java + Spring Boot / Go microservices / Ruby on Rails / .NET / Rust / mixed polyglot]. The development methodology is [METHODOLOGY: Scrum / Kanban / Shape Up / continuous deployment / hybrid]. The target outcome is a new developer making their first meaningful code contribution within [TIMEFRAME: 1 day / 3 days / 1 week / 2 weeks]. ## TASK: COMPLETE ONBOARDING DOCUMENTATION SYSTEM ### Section 1 — Day Zero: Pre-Arrival & Account Setup Create the pre-arrival checklist that the hiring manager or team lead completes before the new developer starts. This includes provisioning accounts for all required services: source code repository access on [PLATFORM: GitHub / GitLab / Bitbucket] with appropriate team and repository permissions, CI/CD platform access on [PLATFORM: GitHub Actions / GitLab CI / Jenkins / CircleCI], cloud provider console access on [PROVIDER: AWS / GCP / Azure / Vercel / Heroku] with least-privilege IAM roles, communication tools including Slack or Teams with correct channel memberships, project management tool access on [PLATFORM: Jira / Linear / Asana / Notion / Shortcut] with appropriate project boards, documentation platform access on [PLATFORM: Notion / Confluence / GitBook / internal wiki], monitoring and observability access on [PLATFORM: Datadog / New Relic / Grafana / PagerDuty], and VPN or network access if required for internal services. Include a hardware setup section covering recommended machine specifications, required peripherals, and whether the company provides standardized development machines or supports BYOD. Define the security onboarding requirements: mandatory 2FA enrollment on all accounts, SSH key generation and upload to the source code platform, GPG key setup for signed commits if required by policy, and completion of the security awareness training module. Provide a timeline showing which accounts should be ready on day one versus which can be provisioned during the first week. ### Section 2 — Day One: Local Development Environment Setup Write the step-by-step local environment setup guide with verification commands at each stage. Begin with operating system prerequisites: [OS: macOS / Linux / Windows with WSL2 / all three] with specific version requirements and any system-level configurations needed. Cover package manager installation using [MANAGER: Homebrew / apt / chocolatey / nix] with the exact commands to install all required system dependencies. Detail the language runtime setup: install [RUNTIME: Node.js / Python / Java / Go / Ruby / Rust / .NET] using version managers like nvm, pyenv, sdkman, goenv, rbenv, or rustup, pinning to the exact version used in production with the version specified in a dotfile (.node-version, .python-version, .tool-versions). Walk through the repository cloning process: git clone with SSH URL, branch naming conventions explanation, and initial checkout of the development branch. Cover dependency installation with the exact package manager command and any common gotchas: native dependency compilation issues, private registry authentication, optional dependencies that require additional system libraries, and cache warming to speed up subsequent installs. Document the database and service setup: local [DATABASE: PostgreSQL / MySQL / MongoDB / Redis / Elasticsearch] installation or Docker Compose configuration that spins up all required services, seed data loading, and schema migration commands. Include the exact command to start the development server with expected output, the URL to verify it is running, and a screenshot or description of what the running application should look like. End with a troubleshooting FAQ covering the [NUMBER: 5-10] most common setup problems reported by previous new hires, with solutions for each. ### Section 3 — Codebase Architecture Orientation Provide the architectural overview that gives new developers a mental map of the entire system. Start with the high-level system diagram showing all services, databases, message queues, caches, CDNs, and external API integrations with arrows indicating data flow direction and protocols used. Describe the repository structure: if monorepo, explain the folder organization and how packages or services relate to each other, and if polyrepo, list every repository with a one-sentence description of its responsibility and how it connects to other repositories. For each major service or module, provide the following: its responsibility in one sentence, the framework and patterns it uses, entry points for incoming requests (API routes, event handlers, cron jobs), outgoing dependencies (databases, other services, external APIs), the most important files that a new developer should read first ([NUMBER: 3-5] files per service), and the data models or schemas it owns. Document the request lifecycle from user action to database and back: trace a representative API call through load balancer, API gateway, authentication middleware, route handler, service layer, data access layer, database query, response transformation, and serialization. Include a dependency diagram showing which services depend on which, with criticality annotations: if this service goes down, these features are affected. Describe the testing architecture: where tests live, how they are organized (unit, integration, e2e), how to run them locally, and what coverage thresholds are enforced. ### Section 4 — Development Workflow & Git Conventions Document the daily development workflow from picking up a task to merging code. Define the branching strategy: [STRATEGY: trunk-based development / GitFlow / GitHub Flow / custom] with naming conventions for branches (feature/TICKET-123-short-description, fix/TICKET-456-bug-name, chore/update-dependencies). Describe the commit message format: [FORMAT: Conventional Commits / custom template / free-form with ticket reference] with examples of good and bad commit messages. Walk through the pull request process step by step: create the branch, make changes, run the local test suite, push the branch, create the PR using the PR template with sections for description, testing steps, and screenshots, request reviews from [REVIEWERS: specific team / code owners file / round-robin assignment], address review feedback, and merge using [MERGE STRATEGY: squash and merge / merge commit / rebase and merge]. Define the code review expectations: turnaround time for reviews ([TIME: same day / 24 hours / 48 hours]), what reviewers should focus on (correctness, readability, test coverage, security, performance), how to handle disagreements (discuss in the PR, escalate to tech lead if unresolved after two rounds), and the minimum number of approvals required before merge. Document the CI/CD pipeline: what checks run automatically (linting, type checking, unit tests, integration tests, security scanning, build verification), how to interpret failures, how to access CI logs, and what happens after merge (automatic deployment to staging, manual promotion to production, or scheduled release train). ### Section 5 — Coding Standards & Team Conventions Compile the coding standards and conventions that are not enforced by automated tooling and therefore must be communicated through documentation. Cover naming conventions for files, functions, variables, classes, database tables, API endpoints, and environment variables with examples of correct and incorrect naming. Document the error handling patterns: how to throw and catch errors, what information to include in error messages, how to log errors with appropriate severity levels, and the standard error response format for APIs. Describe the testing conventions: what to test and what not to test, how to name test files and test cases, how to organize test fixtures and mocks, the required coverage threshold per module, and how to write tests that serve as documentation for the code they cover. List the architectural decisions and patterns the team has adopted: [PATTERNS: repository pattern / service layer pattern / event-driven architecture / CQRS / clean architecture / functional core imperative shell] with brief rationale for each choice and links to the Architecture Decision Records that document them. Include the dependency management policy: how to evaluate and approve new dependencies, maximum acceptable dependency age, procedure for handling security vulnerabilities in dependencies, and the team's stance on [APPROACH: minimal dependencies vs batteries-included frameworks]. Document environment variable management: naming conventions, where they are defined for each environment (local .env file, CI secrets, cloud provider secrets manager), and the procedure for adding a new environment variable across all environments. ### Section 6 — First Week Milestones & Buddy System Define the structured first-week plan that gives new developers concrete goals and a sense of progress. Day 1 should focus exclusively on environment setup and verification, ending with the local development server running and all tests passing. Day 2 should include an architecture walkthrough with their onboarding buddy or tech lead, reading the [NUMBER: 3-5] most important architecture decision records, and completing a codebase scavenger hunt that requires finding specific files, functions, and configuration values to build familiarity. Day 3 should involve picking up a pre-selected starter task (tagged as good-first-issue or onboarding) that is well-defined, low-risk, and touches a representative part of the codebase — the buddy should pair program on this task. Day 4 should focus on completing the starter task, submitting a PR, and experiencing the full review and merge process. Day 5 should involve picking up a second task independently, attending team standup and planning meetings, and having a one-on-one with the engineering manager to discuss initial impressions, blockers, and learning goals. Define the onboarding buddy responsibilities: schedule a daily 30-minute check-in for the first two weeks, be the first point of contact for questions, review all PRs within 4 hours during the onboarding period, proactively share tribal knowledge that is not in documentation, and collect feedback on the onboarding process to improve it for the next hire. Include an onboarding feedback form that the new developer completes at the end of week one and week four, with questions about documentation accuracy, setup difficulty, team support quality, and suggestions for improvement.
Or press ⌘C to copy