Documentation for Onboarding Engineers
How automatic documentation cuts onboarding time and gets new engineers productive faster.
Code Summary Team
Author
New engineer starts Monday. They're smart, experienced, and ready to contribute. By Friday, they've spent the entire week asking questions, sitting in "context transfer" meetings, and still don't understand how the main service works.
This is onboarding at most companies. It's slow. It's expensive. And it's almost entirely caused by missing documentation.
The Real Cost of Slow Onboarding
Think about what happens when a new engineer joins your team:
Week 1: They set up their environment and ask where things are. Senior engineers stop their work to explain the codebase architecture. Multiple times.
Week 2: They pick up a small ticket. They ask more questions. They submit a PR that doesn't follow the patterns because nobody told them about the patterns. Review takes three rounds.
Week 3-4: They're starting to get it. Still interrupting senior engineers regularly. Still discovering "oh, that's how that works" moments daily.
Month 2-3: Finally productive. They've built up the mental model through trial, error, and hundreds of Slack questions.
Now multiply this by every engineer you hire. Multiply it by every senior engineer's interrupted focus time. That's the cost of no documentation.
What New Engineers Actually Need
When someone joins your team, they need to answer fundamental questions:
How is this codebase organized? What are the main services? How do they communicate? Where does business logic live versus infrastructure code?
What are the conventions? How do we name things? Where do new features go? What patterns do we follow for common tasks?
How do I trace a request? If a user clicks a button, what code runs? Where does data flow? What services get hit?
Without documentation, new engineers learn this through archaeology—reading code, making guesses, asking questions when they get stuck. It works, but it's slow and expensive.
What Generated Documentation Looks Like
Code Summary generates exactly the documentation new engineers need. Here's what it produces:
System Architecture:
# System Architecture
## Services Overview
### API Gateway (`services/gateway/`)
Entry point for all client requests. Handles authentication,
rate limiting, and request routing to downstream services.
### User Service (`services/users/`)
Manages user accounts, profiles, and authentication tokens.
Postgres database for persistence.
### Order Service (`services/orders/`)
Handles order creation, updates, and fulfillment workflow.
Communicates with Payment Service and Inventory Service.
### Payment Service (`services/payments/`)
Stripe integration for payment processing.
Webhook handlers for async payment events.
## Communication Patterns
- Synchronous: REST APIs between services
- Asynchronous: RabbitMQ for event-driven workflows
- All inter-service calls go through internal load balancer
## Data Stores
- PostgreSQL: Users, Orders (transactional data)
- Redis: Session cache, rate limiting
- S3: File uploads, generated reportsService Deep-Dive:
# Order Service
## Purpose
Manages the complete order lifecycle from creation to fulfillment.
## Directory Structureservices/orders/ ├── src/ │ ├── controllers/ # HTTP request handlers │ ├── services/ # Business logic │ ├── repositories/ # Database access │ ├── events/ # Message queue handlers │ └── models/ # Data types and validation ├── tests/ └── migrations/ # Database schema changes
## Key Flows
### Order Creation
1. `POST /orders` hits `OrderController.create()`
2. Validates input via `OrderValidator`
3. `OrderService.createOrder()` runs business logic
4. Calls Payment Service to authorize payment
5. Persists to database via `OrderRepository`
6. Publishes `order.created` event to RabbitMQ
### Order Fulfillment
1. Warehouse system calls `POST /orders/:id/fulfill`
2. `OrderService.fulfillOrder()` updates status
3. Triggers payment capture via Payment Service
4. Publishes `order.fulfilled` event
5. Notification Service sends customer email
## Database Schema
- `orders` - Core order data
- `order_items` - Line items per order
- `order_status_history` - Audit trail of status changes
## Environment Variables
- `DATABASE_URL` - Postgres connection string
- `RABBITMQ_URL` - Message queue connection
- `PAYMENT_SERVICE_URL` - Internal payment service endpointDevelopment Patterns:
# Development Patterns
## Code Organization
- Controllers handle HTTP concerns only (parsing, validation, responses)
- Services contain business logic, orchestrate operations
- Repositories abstract database access
- Keep controllers thin, services focused
## Error Handling
```typescript
// Use custom error classes
throw new NotFoundError('Order not found');
throw new ValidationError('Invalid order status');
// Controllers catch and format errors
try {
const order = await orderService.getOrder(id);
return res.json(order);
} catch (error) {
return handleError(res, error);
}Testing Conventions
- Unit tests for services and repositories
- Integration tests for API endpoints
- Test files live next to source:
orderService.test.ts - Use factories for test data:
factories/orderFactory.ts
Common Tasks
Adding a new endpoint
- Add route in
routes/index.ts - Create controller method in
controllers/ - Add service method if new business logic needed
- Write integration test
Adding a database field
- Create migration in
migrations/ - Update model in
models/ - Update repository queries as needed
- Run
npm run migrate
This documentation lives in your repo. New engineers read it on day one. They understand the architecture before asking their first question.
## How This Changes Onboarding
With generated documentation:
**Day 1 is productive.** New engineers read the architecture overview while setting up their environment. By afternoon, they understand how the system fits together.
**Questions get specific.** Instead of "how does this work?", you get "I see the order service publishes events here—does the notification service subscribe to all of them?" Specific questions have specific answers.
**First PRs land faster.** New engineers understand the patterns before writing code. Their PRs follow conventions. Reviews focus on logic, not style corrections.
**Senior engineers stay focused.** The documentation answers the questions they used to answer repeatedly. They review PRs and provide guidance, but they're not the primary source of "how does X work."
**Knowledge survives turnover.** When people leave, their knowledge stays in the documentation. New joiners don't suffer because the person who knew that system is gone.
## Documentation That Stays Current
The reason most teams don't have this documentation: it's hard to maintain. You write onboarding docs, the code changes, and six months later new engineers are reading outdated information.
Code Summary updates documentation on every push. When your architecture evolves, the docs evolve with it. New engineers always get current information, not a historical artifact.
## Get Started
Your next engineer hire doesn't need to spend a month building mental models from scratch. The documentation can exist before they arrive.
[Install on GitHub](https://github.com/apps/codesummaryio)
Connect your repositories, and onboarding documentation generates automatically. By the time your new engineer starts, they'll have everything they need to understand your codebase.