Docs-as-Code a gyakorlatban: Git, Docusaurus, OpenAPI
Beszélj egy nyelvet a fejlesztőcsapattal: minimalizáld a félreértéseket világos szoftverdokumentációval!
Zsámboki Dávid
Senior Technical Writer
Revolut
A KURZUSRÓL
- Időpont:
HAMAROSAN
- Hossz:
12 alkalom
- Formátum:
élő, online
Egy jól megírt dokumentáció olyan, mint a tiszta kód: támogatja a megértésben a fejlesztőt és a felhasználót is. IT-dokumentációírás képzésünkön a kód- és API-dokumentációtól kezdve a felhasználói útmutatókon át az agilis dokumentációs módszerekig gyakorlati feladatokon keresztül ismerheted meg a szoftverdokumentáció területeit, hogy a munkád során egységesebb és következetesebb anyagokat állíthass majd össze.
KINEK AJÁNLJUK A KURZUST?
-
01
Szoftverfejlesztőknek
Tökéletes kódot írtál? Legyen hibátlan a dokumentáció is! A műszaki szövegíró képzésen átfogó ismereteket kapsz az írási alapelvektől kezdve a dokumentációs eszközökön és a verziókövetésen át egészen a minőségbiztosításig. Emellett tippeket adunk az automatizáláshoz, amivel időt spórolhatsz meg.
-
02
Projektmenedzsereknek
Van, ami közös a projektmenedzserben és az átlátható szoftverdokumentációban: hidat képeznek a csapatok között. A képzésen megtanítjuk, hogyan egységesítsd a dokumentációt, miként építs az agilis módszertanokra, és hogyan kommunikálj hatékonyabban a dokumentáción keresztül.
-
03
Kezdő vagy junior technical writereknek
Ha elveszettnek érzed magad a szoftverdokumentációban, a kurzuson olyan praktikus eszközöket ismersz meg, amiket azonnal bevethetsz a munkádban. Megmutatjuk például a Docusaurus, a Swagger/OpenAPI, a GitHub Actions és a Git profi használatát.
Miért válaszd az r_d kurzusait?
MIRE SZÁMÍTHATSZ A KURZUSON?
-
01
Átfogó dokumentációs szemlélet
Szoftverdokumentáció tanfolyamunkon nemcsak a különböző dokumentumtípusokhoz kapcsolódó íráskészséged csiszolására fókuszálunk, hanem rávilágítunk a dokumentációs életciklusra és annak mérföldköveire is, így a dokumentáció ütemezhetőbbé válik a fejlesztési roadmap alapján.
-
02
Docs-as-code
A kurzuson bemutatunk olyan modern eszközöket (pl. Docusaurus, Swagger, GitHub Actions, wiki) és agilis módszereket, amelyekkel a dokumentáció könnyen automatizálhatóvá, verziókövethetővé és folyamatosan frissíthetővé válik.
-
03
Minőségbiztosítás
A képzésen megtanulod a review-process, a peer review és a CI/CD integráció lépéseit, és hangsúlyt fektetünk a dokumentumok hibajavítási folyamatára, hogy növelhesd a tartalom pontosságát és érthetőségét.
-
04
Agilis integráció és csapatmunka
Megmutatjuk, hogyan illesztheted be a dokumentációt a termékfejlesztési sprintekbe és a csapat napi ritmusába. Elsajátítod a kód- és API-dokumentáció alapvető elemeit, és magabiztosan alkalmazod majd a template-alapú megközelítést és a stíluskalauz-technikát.
AZ ELŐADÓ
Zsámboki Dávid
Senior Technical Writer
Revolut
-
Több mint 7 éve dolgozik technical writerként alkalmazotti és szabadúszó formában, így többféle munkakultúrát és csapatdinamikát is megismert.
-
Munkája során többek között verziókövetett API-dokumentációs rendszereket épített ki, illetve junior kollégák betanításában és mentorálásában vett részt.
-
Az Intland Software-nél (ma PTC) senior technical writerként dolgozott, ahol a nulláról hozott létre egy egységes és strukturált információkezelő rendszert.
-
A Revolutnál több termékcsalád dokumentációjáért felel: különböző tartalomtípusok (guide-ok, API/SDK-dokumentációk) előállítását végzi, valamint saját dokumentációs projekteket vezet.
Program
-
01 alkalom
A szoftverdokumentáció alapjai és szerepe
Téma: Mi a szoftverdokumentáció, és miért fontos?
- Különböző dokumentáció- és információtípusok (User guide, Developer guide, API-, SDK-dokumentáció stb.)
- A dokumentáció életciklusa
- A dokumentáció értéke: csapatkommunikáció, tudásmegosztás, fejlesztési hatékonyság
Cél: A résztvevők megértsék a dokumentáció alapvető szerepét és típusait.
-
02 alkalom
Közönségelemzés és technikai írási alapelvek
Téma: Hogyan igazítsuk a dokumentumot a célközönséghez?
- A közönség (fejlesztők, termékmenedzserek, végfelhasználók) és az igényeik
- A világos, tömör és érthető írás elvei (stílus, hangvétel, szerkezet)
- Miért fontos a konzisztens terminológia?
Cél: A résztvevők tudatosan válasszák meg a stílust és a szerkezetet a különböző célcsoportoknak.
-
03 alkalom
Dokumentációs eszközök: Markdown, Git, „docs-as-code” alapok
Téma: Technikai hátterek és workflow-k
- Markdown és egyéb leíró nyelvek
- A Git verziókezelés bemutatása (branch, pull request, review)
- Alapvető docs-as-code gondolkodásmód
Cél: A résztvevők ismerjék a modern dokumentációs eszközöket, és betekintést nyerjenek a „docs-as-code” megközelítésbe.
-
04 alkalom
Felhasználói dokumentáció és útmutatók
Téma: User guide, admin guide, GYIK, tutorialok
- Lépésről lépésre útmutatók készítése (telepítés, konfigurálás, alapfunkciók)
- Képernyőképek, illusztrációk használata
- „What’s next?” szekciók és az IA (információarchitektúra) szerepe
Cél: A résztvevők képesek legyenek világos, felhasználó-központú kézikönyveket írni.
-
05 alkalom
API-dokumentáció: Swagger/OpenAPI használata
Téma: API-specifikációk és generálás
- Mi az API-dokumentáció, és miért létfontosságú?
- Swagger/OpenAPI alapok: fájlszerkezet, paraméterek, válaszkódok
- Kódsnippek és példák integrálása
Cél: A résztvevők tudják, hogyan kell jól felépített API-dokumentációt készíteni és karbantartani.
-
06 alkalom
Kóddokumentálás és kommentelés
Téma: Fejlesztői szemlélet és kódszintű dokumentáció
- Módszerek és best practice-ek a kódkommentek írásához
- Automatikus dokumentációgenerátorok
- Metódusleírások, bemenet/kimenet felépítése
Cél: A résztvevők képesek legyenek olyan kóddokumentációt írni, amely valóban segíti a fejlesztői munkát.
-
07 alkalom
Agilis dokumentációs módszerek: sprinttervezés, review
Téma: Hogyan illeszkedik a dokumentáció az agilis fejlesztési ciklusba?
- Dokumentációs „sprint” és backlog
- Stakeholderbevonás, rendszeres review
- Folyamatos frissítés, felülvizsgálat
- Integráció a termékéletciklusba
Cél: A résztvevők megtanulják, miként ütemezzék és kövessék nyomon a dokumentációs feladatokat a sprintek során.
-
08 alkalom
Docusaurus: projektfelépítés és navigáció
Téma: Modern dokumentációs keretrendszerek használata
- Docusaurus telepítés, mappa- és fájlszerkezet
- Oldalsáv, navigáció beállítása
- Template-alapú írás: egységes arculat és felhasználói élmény
Cél: A résztvevők gyakorlati példán keresztül megtanulják, hogyan építsenek fel egy docs-as-code alapú weboldalt.
-
09 alkalom
Docusaurus: API-dokumentáció, pluginek és automatikus generálás
Téma: OpenAPI-dokumentáció közzététele és karbantartása
- Docusaurus pluginek használata saját API-oldalak létrehozásához
- Integrációs lépések: build, deploy
- API verziókezelési stratégiák
Cél: A résztvevők lássák, hogyan kombinálhatják az API-leírásokat és a felhasználói dokumentumokat egy egységes platformon.
-
10 alkalom
Verziókövetés és CI/CD a dokumentációban
Téma: Miért fontos a folyamatok automatizálása a dokumentációk esetében?
- Alapvető CI/CD fogalmak (build, teszt, deploy, integrációs folyamatok)
- Hogyan automatizálható a dokumentáció generálása és publikálása? (pl. statikus oldalak automatikus frissítése)
- GitHub Actions mint példa a folyamatra
Cél: A résztvevők elméleti szinten megértsék, miként segíti a dokumentáció naprakészen tartását az automatizált build- és deployfolyamat, és megismerjenek egy egyszerű gyakorlati példát.
-
11 alkalom
Minőségbiztosítás, review és karbantartás
Téma: Hogyan őrizzük meg a dokumentáció minőségét hosszú távon?
- Peer review folyamat, stíluskalauz, checklist
- A felhasználói feedback beépítése
- Dokumentációarchiválás, verzióváltás
Cél: A résztvevők megismerjék a tartós minőségbiztosítás és a folyamatos karbantartás gyakorlati lépéseit.
-
12 alkalom
Záró alkalom: esettanulmány, jövőbeli trendek és összegzés
Téma: Kurzus-összefoglaló, jövőbeli lehetőségek és AI-eszközök
- Egy komplex dokumentációs projekt közös áttekintése, tapasztalatok megbeszélése
- Kérdések-válaszok, konkrét példák átbeszélése
- Aktuális trendek a dokumentáció világában: LLM/AI-alapú támogatás, automatizált doc-checking, docs-as-code evolúció
- Továbblépési lehetőségek, fejlesztési irányok
Cél: A résztvevők átfogó képet kapjanak az elsajátított módszerekről és eszközökről, valamint inspirációt nyerjenek a jövőbeni fejlesztésekhez (AI, továbbfejlesztett automatizálás, új eszközök).