Writing Effective Project DescriptionsLesson 4.3

How to document technical decisions in a project for interviews

architecture decision records, why over what documentation, trade-off discussion, technology choice rationale, known limitations, future improvements section

Document Why, Not What

Code documents what you built. Comments document how it works. The missing layer — the one that impresses interviewers — is why you made the decisions you did.

The Architecture Decision Record (ADR) Pattern

Add a docs/decisions/ folder to your project with one markdown file per major decision:

# ADR-001: State Management Choice

## Context
The app needs to share user authentication state across 8+ components.

## Decision
Used React Context API instead of Redux.

## Trade-offs
- Context is built-in and simpler for this scale
- Redux would add boilerplate overhead not justified at <1,000 daily users
- If the app grows beyond 20 components, Redux Toolkit would be revisited

## Rejected Alternatives
- Zustand: less familiar, adds a dependency for marginal benefit at this scale
- Prop drilling: impractical across more than 3 component levels

What to Document

Document decisions for: database choice, state management approach, API design pattern, authentication strategy, and any place you chose the non-obvious option.

You do not need formal ADR files. A "Technical Decisions" section in your README works equally well. What matters is that when an interviewer asks "why did you use X instead of Y," you have a real answer prepared — and your project proves you thought about it.