Dokumentáció, mint kód: Egy forradalmi újítás a DevOps csapatok számára?

A dokumentáció, mint kód (Documentation As Code - DaC) egy egyre elterjedtebb irányzat a szoftverfejlesztés világában. Ez a megközelítés a szoftverdokumentációt ugyanúgy kezeli, mint a szoftverkódot. Vagyis a dokumentációt ugyanúgy írjuk, kezeljük, tároljuk és szállítjuk, mint a kódot, ezzel elősegítve a hatékony és eredményes együttműködést a fejlesztési és üzemeltetési csapatok között.

A dokumentáció kódként való kezelése, lehetővé teszi a "shift-left" megközelítést, ami azt jelenti, hogy a dokumentációt minél előbb és gyakrabban kell elkészíteni, valamint frissíteni. Mindez sokkal precízebb, naprakészebb és relevánsabb dokumentációt eredményez, hiszen az a kód változásával párhuzamosan frissül. Mivel a dokumentációt kódként kezelik, a fejlesztési folyamat részévé válik, nem pedig utólagos feladattá. Ez segít áthidalni a fejlesztés és az üzemeltetés közötti szakadékot, megkönnyítve a csapatoknak a magas minőségű szoftverek gyorsabb szállítását.

A DaC koncepció 5 alapelve

1. Verziókezelés

A dokumentáció, mint kód egyik kulcsfontosságú eszköze a verziókezelés. Pontosan úgy, mint a kódbázis, a dokumentáció is folyamatosan változik, fejlődik. A régi funkciók elavulnak és eltávolításra kerülnek, új funkciókkal bővül a rendszer, valamint a hibák javításáról sem feledkezhetünk meg. Ezért is szükséges, hogy nyomon kövessük a változásokat és szükség esetén legyen lehetőségünk egyszerűen visszatérni a korábbi verziókhoz.

A verziókezelő rendszerek, mint például a Git, tökéletesek a dokumentáció kezelésére is. Lehetővé teszik a változások nyomon követését, a dokumentumok különböző verzióinak létrehozását és a különböző részek módosításainak összevonását. Ez megkönnyíti a dokumentációban való együttműködést, illetve biztosítja, hogy mindig legyen nyoma a változtatásoknak.

2. Egyszerű szöveges formátumok

A dokumentáció kódként történő kezelésének másik alapelve az egyszerű szöveges formátum használata, mint például a Markdown vagy a reStructuredText. Ezek könnyen olvashatóak és írhatóak, valamint támogatják a verziókezelést és különböző változatok összehasonlítását.

Ezen kívül, az egyszerű szöveges formátumok platformfüggetlenek, ami azt jelenti, hogy bármilyen operációs rendszeren olvashatóak és szerkeszthetőek. Ez hatalmas előnyt jelent a zárt formátumokkal szemben, mint például a Word, amelyekhez speciális szerkesztő szoftverre van szükség és nem feltétlenül kompatibilisek egymással a különböző platformok.Továbbá ha publikálni kell a dokumentációt az egyszerű szöveges formátumok könnyen átalakíthatóak más formátumokra, például HTML-re vagy PDF-re.

A dokumentációt tehát megírhatod egyszerű szöveges formátumban, majd különböző kimeneti formátumokat generálhatsz az eltérő célok vagy célcsoportok számára.

3. Együttműködés és szakértői értékelés

A DaC elősegíti a közös munkát, mivel a dokumentáció egyszerű szöveges formátumban egy verziókezelő rendszerben van tárolva, így a csapat bármely tagja könnyen hozzáférhet. A fejlesztők, a tesztelők, az üzemeltetők és még az ügyfelek is hozzájárulhatnak a folyamathoz, ami átfogóbb és pontosabb dokumentációt eredményez.

Az együttműködés megkönnyítése mellett, a kódként történő dokumentáció ösztönzi a szakértői ellenőrzést is. A kódhoz hasonlóan a dokumentáció is jobb lehet azáltal, ha többen felülvizsgálják. Ez segíthet a hibák feltárásában, az átláthatóság javításában és a következetesség biztosításában. A verziókezelő rendszerek beépített eszközökkel rendelkeznek a kód jóváhagyásához, amelyek a dokumentációhoz is használhatók. Ez a fejlesztők számára lehetővé teszi a kódminőség ellenőrzését és javítását, illetve ezek az eszközök segíthetnek az esetleges hibák vagy hiányosságok felderítésében.

Például egy merge request-nél a fejlesztők megjegyzéseket és észrevételeket tudnak hozzáadni a kódhoz, ami utána bekerülhet a dokumentációba is.

4. Automatizált tesztelés és telepítés

A kódhoz hasonlóan a dokumentációt is lehet és célszerű is automatizáltan tesztelni, ami segíthet az olyan hibák feltárásában, mint a hibás hivatkozások, a hiányzó képek vagy a helytelen formázás. Számos olyan eszköz áll rendelkezésre, amely képes automatikusan tesztelni a dokumentációt és integrálható a CI/CD (Continuous Integration and Continuous Deployment) folyamatokkal a dokumentáció automatikus frissítése érdekében, amikor a kódbázis változik.

A tesztelés mellett a dokumentáció is szállítható automatikusan. Amikor például változik a dokumentáció, a CI/CD pipeline telepítéskor automatikusan kirakhatja a frissített dokumentációt a webhelyre vagy a dokumentációs portálra. Ez biztosítja, hogy dokumentáció mindig naprakész legyen és megfeleljen a szoftver aktuális állapotának.

5. “Az igazság egyetlen forrása”

A DaC koncepció utolsó alapelve az úgynevezett, “Single Source Of Truth” (SSOT) szemléletmód. Az SSOT koncepció azt jelenti, hogy az adatok vagy információk esetében csak egyetlen, megbízható forrás létezik, ahol azok tárolva és karbantartva vannak. A DaC koncepció is ezt az elvet követi, ennek értelmében az összes adatot vagy információt egy központi forrásból származtatják és az összes többi rendszer, alkalmazás vagy folyamat erre az egy forrásra támaszkodik.

Az SSOT szemléletmód előnyei közé tartozik a konzisztencia, a megbízhatóság és az egyszerűség.Azonos adatforrás használata esetén, kevesebb a hiba lehetősége és a fejlesztési folyamatok hatékonyabbá válnak, az adatok egyszerűbb elérhetőségének és karbantartásának köszönhetően.

Ez a koncepció tehát biztosítja a következetességet a dokumentáció minden verziójában, ezenkívül megkönnyíti a dokumentáció kezelését és frissítését, mivel csak egy forrás frissítését kell végrehajtani.

A kódalapú dokumentáció előnyei a DevOps csapatok számára

Jobb együttműködés

A hagyományos rendszerekben a dokumentációt gyakran másodlagos szempontként kezelik és gyakran csak a tényleges kódolás befejezése után foglalkoznak vele. Azonban a DaC koncepció segítségével a dokumentáció integrált részévé válik a kódnak. Ennek révén elősegíti a felelősség megosztást és a jobb megértést, és ösztönzi az együttműködés kultúráját.

Nagyobb következetesség és pontosság

A DaC megközelítés garantálja, hogy a dokumentumaink megfeleljenek az előre meghatározott szabványoknak és hibamentesek legyenek. Ezzel automatikusan ellenőrzi a kifejezések, formázás és struktúra következetességét, megszüntetve a kézi munkát és minimalizálva az emberi hibák lehetőségét. Emellett, a dokumentáció a kóddal együtt van jelen, így mindig pontosan tükrözi a rendszer aktuális állapotát.

Optimalizált frissítési és karbantartási folyamatok

A hagyományos dokumentáció gyakran gyorsan elavulttá válik, melynek frissítése jelentős idő befektetést és erőfeszítést igényel. A DaC segítségével azonban a frissítések integrált részévé válnak a fejlesztési folyamatnak. A kód változtatásával a dokumentáció is automatikusan frissül . Ezáltal megoldódik a külön dokumentációval járó frissítések problémája, melynek köszönhetően a dokumentáció mindig naprakész marad.

A DaC legjobb gyakorlatai a DevOps csapatok számára

Íme néhány legjobb gyakorlat, amelyek segítenek hatékonyan megvalósítani a dokumentáció kódként való implementálását a DevOps folyamatokba.

Kezdd el időben!

Az egyik legfontosabb tanácsunk, hogy kezdd el mihamarabb a dokumentálást, már az első kódsortól! Ez biztosítja, hogy a dokumentáció szervesen együtt fejlődjön a kóddal, valamint csökkenti annak a valószínűségét, hogy fontos részletek elfelejtődnek vagy kimaradnak.

Használj egyszerű jelölő (markup) nyelveket

A DaC megvalósításakor célszerű olyan könnyű markup nyelveket használni, mint a Markdown vagy az AsciiDoc. Ezek könnyen megtanulhatóak és használhatóak, illetve lehetővé teszik, hogy olyan dokumentációt írj, amely mind nyers formában, mind HTML vagy más formátumban megjelenítve könnyen értelmezhető.

Dokumentációs felülvizsgálat és visszajelzési folyamat

A kód felülvizsgálatához hasonlóan, a dokumentáció ellenőrzése is rendszeres része kell, hogy legyen a fejlesztési folyamatnak. Ez biztosítja, hogy a dokumentáció pontos és átfogó legyen, valamint megfeleljen a csapat által használt szabványoknak. Javasoljuk, hogy építs be egy visszajelzési folyamatot is a dokumentációs folyamatba. Ez lehetővé teszi a csapat számára, hogy a felhasználók és az érintettek visszajelzései alapján a dokumentáció folyamatosan javuljon.

Moduláris felépítés és többszöri alkalmazás

És végül, tervezd meg dokumentációdat a modularitás és az újrafelhasználhatóság jegyében. Bontsd szét apró, könnyen kezelhető részekre, amelyek könnyen frissíthetőek és többször felhasználhatóak az alkalmazás különböző részeiben.

Összefoglalás

Véleményünk szerint a megfelelően elkészített dokumentáció egy felbecsülhetetlen értékű eszköz a DevOps csapatok számára, hiszen javítja az együttműködést, biztosítja a konzisztenciát és a pontosságot, megkönnyíti a verziókezelést és egyszerűsíti a frissítési és karbantartási folyamatokat. Amennyiben követed az itt felvázolt legjobb gyakorlatok listájába szedett alpontokat, garantáltan kihasználhatod a DaC módszerben rejlő potenciált és jelentősen növelheted csapatod hatékonyságát és eredményességét.

A Devertixnél évtizedes tapasztalatunk van DevOps folyamatok megtervezésében és megvalósításában. Ha szeretnéd felmérni, hogy milyen állapotban vannak DevOps folyamataid, ajánljuk figyelmedbe ingyenes, DevOps érettségi felmérésünket. Ha pedig szeretnél új szintre lépni a DevOps-ban, vagy bevezetni a megfelelő dokumentációs folyamatot, de nem tudod, hogy mik a legjobb gyakorlatok és az ezeket támogató eszközök, lépj velünk kapcsolatba, hogy segíthessünk!