# Contributing

Thanks for wanting to make this better. This repo has one goal: **a beginner should be able to
start at zero and finish able to pass a system design interview at any company.** Every
contribution is judged against that.

## What's welcome

- **Corrections.** Wrong numbers, outdated tech, broken reasoning. These are the most valuable
  contributions. Open an issue even if you can't fix it yourself.
- **Clarity improvements.** If a paragraph confused you, it will confuse a thousand other people.
  Rewrite it.
- **New case studies.** Follow the [template](#case-study-template) exactly.
- **Real interview questions** you were asked (no NDA violations, no verbatim leaks of proprietary
  material — just the shape of the question, e.g. "design a system that dedupes events at 1M/s").
- **Diagrams.** Mermaid preferred over images, because they diff well and stay editable.

## What isn't

- Link dumps without explanation.
- Content copied from books, courses, or blogs. Write it in your own words or don't add it.
- Framework/library tutorials. This repo is about *design*, not about how to configure Spring Boot.
- "Just use Kubernetes" advice with no trade-off discussion.

## File naming

Every chapter file is prefixed with a two-digit number giving its **reading order within its
folder**:

```
01-foundations/
├── README.md                    ← folder index, never numbered
├── 01-computer-fundamentals.md
├── 02-networking-basics.md
├── 03-tcp-udp-ip.md
└── …
```

Rules:

- Numbers reflect the order a beginner should read them, not alphabetical order.
- Folders are numbered too (`00-getting-started`, `01-foundations`, …).
- `README.md` inside a folder is the index for that part and is never numbered.
- Slugs are lowercase kebab-case, no dates, no author names.
- **Inserting a chapter in the middle?** Renumber the ones after it and fix inbound links. Yes, it's
  a bigger diff — the alternative is `07b-thing.md`, which rots fast.

## Writing style rules

These are non-negotiable, because consistency is what makes a 200-file repo readable.

1. **Why before what.** Never introduce a component before establishing the problem it solves.
   Bad: *"A load balancer distributes traffic across servers."*
   Good: *"One server can handle 10k connections. You have 100k users. Now what?"*
2. **Second person, present tense.** "You store the session in Redis," not "one would store…".
3. **Numbers, always.** "Fast" is meaningless. "p99 of 40 ms" is a claim you can defend.
4. **No unexplained jargon.** The first time a term appears in a chapter, define it inline and link
   to the [Glossary](./00-getting-started/05-glossary.md).
5. **Trade-offs are mandatory.** Every technique section must state what it costs. A chapter that
   only lists benefits is marketing, not engineering.
6. **Short paragraphs.** 1–4 sentences. Dense walls of text are where beginners quit.
7. **Line length ≤ 100 characters** in Markdown source.

## Chapter template

```markdown
# <Title>

> One-sentence summary of what this chapter gives you.

**Prerequisites:** [link](…), [link](…)
**Time to read:** ~N minutes

---

## The problem
(Concrete scenario where the naive approach breaks. Use numbers.)

## 🧠 Mental model
(An analogy from outside computing.)

## How it works
(The mechanism, built up in stages. Diagrams here.)

## ⚖️ Trade-offs
(Table: what you gain / what you pay.)

## In the real world
(How an actual company uses this, with a link to their engineering blog.)

## 🚨 Interview traps
(Bulleted list of mistakes.)

## 🎙️ Soundbites
(3–5 sentences the reader can say verbatim in an interview.)

## 🛠️ Try it
(A hands-on exercise.)

## Check yourself
(5 questions. Answers in a collapsed <details> block.)

## Further reading
```

## Case study template

```markdown
# Design <System>

**Difficulty:** Tier 1 / 2 / 3   **Asked at:** …   **Time budget:** 45 min

1. Requirements (functional, non-functional, explicitly out of scope)
2. Back-of-the-envelope estimation
3. API design
4. Data model
5. High-level design (diagram)
6. Deep dives (3–4, the ones an interviewer will actually push on)
7. Bottlenecks and how you'd scale further
8. Trade-off summary table
9. Follow-up questions an interviewer may ask (with answers)
10. What "junior / mid / senior" answers look like for this problem
```

## Diagrams

Use Mermaid — it renders on GitHub and stays editable:

````markdown
```mermaid
flowchart LR
    Client --> LB[Load Balancer]
    LB --> S1[Server 1]
    LB --> S2[Server 2]
    S1 --> DB[(Database)]
    S2 --> DB
```
````

For anything Mermaid can't express, ASCII art is preferred over a PNG. If you must use an image,
put it in `assets/` and always provide alt text.

## Commits

- One logical change per commit.
- Subject line in the imperative mood, ≤ 72 characters: `Add chapter on consistent hashing`.
- No body unless the change genuinely needs explaining.

## Pull requests

1. Fork, branch (`add/kafka-chapter` or `fix/latency-numbers`).
2. Keep PRs focused — one chapter or one fix. A 40-file PR will not get reviewed.
3. Check your links work and Mermaid blocks render (GitHub previews them).
4. In the description, say who the change helps: *"A reader who's never seen a queue would have
   been lost at paragraph 3; this adds the missing step."*

## Code of conduct

Be kind. This repo exists for people who don't know things yet. Condescension in reviews,
issues, or content will get the contribution rejected regardless of technical merit.