← 8. Production-ready projekt építés

8.4 README és dokumentáció írása

Áttekintő

Láttál már olyan projektet GitHubon, ahol a README annyi, hogy „TODO: write docs"? Vagy ahol a setup 3 óra kínlódás volt, mert senki nem írta le, hogy kell futtatni? Ez a hiányzó dokumentáció valós munkahelyi probléma – időt, energiát és türelmet emészt fel. Egy jól megírt README nem udvariassági gesztus, hanem a projekt alapinfrastruktúrájának része.

Ez az alfejezet arról szól, mi kerüljön be egy README-be minimálisan, hogyan dokumentálj API végpontokat alapszinten, és mikor kell a README-n túlmenni. Nem írástechnikai kurzus – a cél az, hogy mindig legyen elég dokumentáció ahhoz, hogy egy új csapattag (vagy te magad 3 hónap múlva) el tudjon indulni a projekt alapján.

Miért számít ez az állásinterjún? Portfolio projektjeid README-je az első benyomás. Ha egy recruiter vagy senior developer megnézi a GitHub-profilodat, a hiányos README azt jelzi: „ez a fejlesztő nem gondol arra, hogy mások is dolgoznak a kóddal." Egy jó README viszont azt mutatja, hogy production-gondolkodásod van – és ez ritka a juniorok körében.

Miért számít production környezetben? Minden percnyi leállás pénzbe kerül. Ha egy deployment közben problémád van és az onboarding dokumentáció hiányos, az egész csapat lelassul. A dokumentáció nem mellékterméke a munkának – a munka része.

---

Részletes leírás

Mi a README valódi célja?

A README nem önmagának való – mindig valaki másnak szól. Ez lehet:

• Egy új csapattag, aki a projekten dolgozik
• A jövőbeli önmagad (6 hónappal később, amikor már semmire sem emlékszel)
• Egy recruiter, aki értékelni szeretné a portfoliódat
• Egy külső fejlesztő, aki az API-dat használja

Ez az egyetlen kérdés, amit feltegyél magadnak README-íráskor: „Mit kell tudnia annak, aki most lép be a projektbe?"

---

A minimális README – ami mindig benne legyen

1. Projekt neve és rövid leírás

Egy-két mondat: mi ez és mire való. Nem marketingszöveg – tömör, pontos leírás.

# Task Manager API

REST API feladatkezelő alkalmazáshoz. Felhasználók létrehozhatnak, módosíthatnak
és törölhetnek feladatokat, priorizálhatják őket és hozzárendelhetik másokhoz.

2. Előfeltételek (Prerequisites)

Mi szükséges a futtatáshoz? Ne feltételezd, hogy mindenki tudja.

## Előfeltételek

- Node.js 18+
- PostgreSQL 14+
- npm vagy yarn

Vagy:

## Előfeltételek

- Python 3.11+
- pip
- Docker és Docker Compose (opcionális, de ajánlott)

Tipikus hiba: „Majd tudják, hogy kell PHP." – Nem fogják tudni, melyik verzió kell, és melyik extensionök szükségesek.

3. Telepítés és indítás (Getting Started)

Lépések, amelyeket ha sorban követ valaki, el tudja indítani a projektet. Semmi nem bosszantóbb, mint az, amikor egy lépés hiányzik és csak próbálgatással jön rá az ember.

## Telepítés

1. Repository klónozása:
   ```bash
   git clone https://github.com/username/task-manager-api.git
   cd task-manager-api
   ```

2. Függőségek telepítése:
   ```bash
   npm install
   ```

3. Környezeti változók beállítása:
   ```bash
   cp .env.example .env
   # Töltsd ki a .env fájlt a saját értékeiddel
   ```

4. Adatbázis migrálása:
   ```bash
   npm run migrate
   ```

5. Szerver indítása:
   ```bash
   npm run dev
   ```

Az alkalmazás elérhető: http://localhost:3000

Fontos: Teszteld le, hogy a saját leírásod valóban működik-e! Klónozd le a saját repódat egy üres könyvtárba, és kövesd a lépéseket. Meglepő, hány fejlesztő ezt soha nem teszi meg.

4. Environment változók listája

Minden szükséges változó, rövid magyarázattal, hogy mi az. Az értékeket ne írd bele – csak azt, hogy mit kell beállítani.

## Környezeti változók

| Változó | Leírás | Példa |
|---------|--------|-------|
| `DATABASE_URL` | PostgreSQL connection string | `postgresql://user:pass@localhost:5432/db` |
| `JWT_SECRET` | JWT token titkosítási kulcs | Bármilyen hosszú véletlenszerű string |
| `PORT` | Alkalmazás portja | `3000` |
| `NODE_ENV` | Futtatási környezet | `development` / `production` |

Ezt a táblázatot mindig szinkronban tartsd a .env.example fájllal. Ha hozzáadsz egy új változót, frissítsd mindkettőt.

5. Tesztek futtatása

## Tesztek

npm test # Összes teszt npm run test:unit # Csak unit tesztek npm run test:coverage # Coverage riport

---

API dokumentáció alapok

Ha az alkalmazásod API-t tesz közzé, a README-ben legalább az alapvégpontokat érdemes dokumentálni.

Minimális API leírás – egy endpoint esetén:

### POST /api/tasks

Új feladat létrehozása.

**Request body:**

{ "title": "string (kötelező)", "description": "string (opcionális)", "priority": "low | medium | high (default: medium)" }

**Válasz (201 Created):**

{ "id": 42, "title": "Dokumentációt írni", "priority": "high", "createdAt": "2026-05-01T10:00:00Z" }

**Hibák:**
- `400 Bad Request` – hiányzó kötelező mező
- `401 Unauthorized` – érvénytelen vagy hiányzó token

Mikor elég a README API-dokumentáció? Kis projekteknél, ahol 5-10 végpont van és belső csapatnak szól. Ha több végpont van, vagy külsős fejlesztők használják az API-t, érdemes Swagger/OpenAPI vagy egy dedikált dokumentációs eszköz (pl. Postman Collection) felé elmenni.

---

Mikor kell a README-n túlmenni?

A README nem mindig elég. Íme a jelek:

A legtöbb junior projekthez elegendő egy jó README. Ne csináld túl bonyolulttá – amit nem tartasz karban, az rosszabb a semminél.

---

Dokumentáció karbantartása

Ez az, ami a legtöbbször elmarad. A dokumentáció elavul, ha nem tartod frissen.

Gyakorlati megközelítés:

• Ha megváltoztatod egy endpoint paraméterét → frissítsd a README-t ugyanabban a PR-ban
• Ha új environment változó kell → frissítsd .env.example-t és a README-t egyszerre
• Ha megváltozik a setup folyamat → teszteld le és frissítsd a leírást

Egyszerű ökölszabály: ha egy PR megváltoztat valamit, ami a README-ben le van írva, a PR nem kész addig, amíg a README is frissül.

A code review során a reviewerek egyre inkább elvárják, hogy a dokumentáció változzon a kóddal együtt. Ez nem extra pontért van – ez az alapelvárás.

---

Életszerű példák

1. A „setup rémálom" esete

Képzeld el: új fejlesztő kerül a csapatba. Klónozza a repót, nyitja a README-t, és ezt látja:

# My Awesome App

Cool project. Uses React and Node.

## Setup
1. npm install
2. fill in .env
3. run

Mi hiányzik?

• Milyen Node verzió kell?
• Milyen .env változók kellenek és mik az értékek?
• Hogyan kell futtatni? (npm start? npm run dev? valami más?)
• Van adatbázis? Azt hogyan kell beállítani?

Ez a fejlesztő 2-3 órát tölt azzal, hogy megtalálja a válaszokat, Slack-en megkérdez mindenkit, és a végén dühös lesz. Ez teljesen megelőzhető lett volna.

---

2. A jó README hatása recruiterrel

Két junior fejlesztő portfolióját nézi egy senior developer:

Első fejlesztő: A projekt README-je részletes, van setup leírás, environment változó táblázat, és az API végpontok is dokumentálva vannak. A kód megnézése nélkül is érthető, hogy mi a projekt.

Második fejlesztő: A projekt README-je: „Todo app written in JavaScript." Ez az egész.

Melyiket hívják be? A kód minőségétől függetlenül az első fejlesztőt, mert az ő munkájából azt is látja, hogy gondol a kommunikációra és a csapatmunkára.

---

3. README sablon, amit érdemes megtartani

Az alábbi sablon jó kiindulópont minden projekthez:

# [Projekt neve]

[Rövid leírás – 1-2 mondat]

## Előfeltételek

- [Runtime/language] [verzió]+
- [Adatbázis vagy más függőség]

## Telepítés

git clone [repo url] cd [projekt mappa] [telepítés parancs] cp .env.example .env

## Konfiguráció

Másold a `.env.example` fájlt `.env`-be és töltsd ki:

| Változó | Leírás |
|---------|--------|
| `VÁLTOZÓ_NEVE` | Mit jelent |

## Futtatás

[fejlesztői szerver indítás]

## Tesztek

[tesztek futtatása]

## API dokumentáció

[Ha releváns: rövid végpont lista vagy link a teljes docs-hoz]

Ez nem végleges formátum – igazítsd a projekted igényeihez.

---

4. Meghibásodott dokumentáció veszélye

Prod incident: éjjel 2-kor leáll egy service. Az oncall mérnök meg akarja nézni, hogyan kell kézzel újraindítani az alkalmazást. Megnyitja a runbookot (részletes üzemeltetési dokumentációt) – és 6 hónapja elavult. A parancsok nem működnek, mert a deploy folyamat megváltozott, de senki nem frissítette a dokumentációt.

Ez valós forgatókönyv, és rengeteg időt és pénzt emészt fel. A dokumentáció karbantartásának elmulasztása production kockázat.

---

Tesztfeladatok

1. feladat – Elemzés

Az alábbi README-t nézed egy junior fejlesztő portfolió-projektjéből:

# Weather App

Gets weather data. Built with Python.

Requirements:
- Python
- pip install requests

Usage:
python app.py

Sorolj fel legalább 4 konkrét hiányt, amelyek miatt ezt a README-t nem tekintheted production-ready-nek!

---

2. feladat – Döntés

Melyik állítás igaz a .env.example fájlról?

A) A .env.example-be bele kell írni a valódi API kulcsokat, hogy mások tudják, milyen formátumban kell megadni
B) A .env.example csak a változók neveit és magyarázó placeholder értékeket tartalmaz, soha nem valódi titkokat
C) A .env.example-t nem kell verziókezelni – mindenki a saját .env fájlját használja
D) A .env.example és a README environment változó szekciója mindig ugyanazokat az értékeket tartalmazza

---

3. feladat – Sorrend

Tedd sorrendbe a következő README-szekciók logikus sorrendjét:

• Tesztek futtatása
• Projekt neve és leírás
• Environment változók
• Előfeltételek
• Telepítési lépések

---

4. feladat – Helyes vagy helytelen?

Egy csapattársad ezt mondja: „Nem kell a README-t frissíteni minden PR-ban. Ha valami nagyot változtatunk, akkor majd külön frissítjük a dokumentációt."

Értékeld ezt a megközelítést! Mi a probléma vele, és hogyan csináld helyesen?

---

5. feladat – API dokumentáció

Az alábbi API végpont leírása hiányos. Egészítsd ki a hiányzó részekkel:

### GET /api/users/:id

Visszaadja az adott ID-jű felhasználó adatait.

Válasz:
{
  "id": 5,
  "name": "Kiss János",
  "email": "kiss.janos@example.com"
}

Mi hiányzik belőle? Legalább 3 hiányt nevezz meg, és írj hozzájuk javaslatot!

---

6. feladat – Mikor kell több?

A csapatodban vita van: egy junior azt mondja, hogy a README elegendő. Egy senior szerint docs/ mappa kell, benne architecture.md, deployment.md, api.md.

Melyik állításhoz értesz egyet, és mikor változtatnál véleményt?

A) Mindig elég a README – a komplex projektek sem igényelnek külön docs mappát
B) Ha a projekt kicsi és belső csapatnak szól, a README általában elegendő; ha nő a komplexitás vagy külsős használók is vannak, külön dokumentáció szükséges
C) Minden projektnek legyen docs/ mappa, README-ben csak a hivatkozás legyen
D) A dokumentáció mennyisége nem számít, csak a kód minősége

---

7. feladat – Hibakeresés

Egy új csapattag ezt írja Slacken: „Követtem a README-t, de a 4. lépésnél hibát kapok: command not found: migrate."

Mik lehetnek az okai? Legalább 2 lehetséges problémát nevez meg, és írd le, hogyan deríted ki melyik az igazi ok!

---

8. feladat – Prioritizálás

Egy junior fejlesztő az alábbi README-elemeket szeretné megírni, de kevés ideje van. Rangsorolja őket fontosság szerint (1 = legfontosabb):

• Changelog az eddigi verziókhoz
• Setup utasítások (telepítés + indítás)
• Contribution guide (hogyan járuljon hozzá más)
• Environment változók listája és magyarázata
• Projekt neve és rövid leírás
• Badge-ek (build status, coverage stb.)

Indokold a sorrendet!

---

9. feladat – Valós szituáció

Portfolio-projektedet megnézi egy senior fejlesztő, és azt mondja: „A kód rendben van, de nem látom, hogyan kell ezt a projektet futtatni."

Mit teszel azonnal? Írj egy rövid lépéssort, amivel orvosolod a helyzetet!

---

10. feladat – Összefoglalás

Igaz vagy hamis?