A dokumentáció a szoftverfejlesztési ciklus elengedhetetlen része. Elmagyarázza a szoftver használatát, és tartalmazhat felhasználói útmutatókat, API hivatkozásokat, telepítési utasításokat és kiadási megjegyzéseket.
A dokumentáció automatizálása a legújabb trend, mivel időt takaríthat meg, csökkentheti a hibákat és biztosíthatja a konzisztenciát. A dokumentáció naprakészen tartása és minden érdekelt fél számára elérhetősége megkönnyíti az együttműködést és a folyamatos fejlesztést.
A Dokumentumok kódként a dokumentáció automatizálásának egy olyan megközelítése, amely a műszaki dokumentációt kódként kezeli.
Mi a dokumentumok kódként?
A Dokumentumok kódként egy olyan szoftverfejlesztési filozófia, amely a műszaki dokumentációt a kód egy formájaként tekinti. Azt javasolja, hogy a dokumentációt ugyanolyan szigorúsággal és eljárással kezelje, mint a szoftverkódot.
A docs mint kód mögött meghúzódó gondolat az, hogy a dokumentációt a fejlesztési folyamat első osztályú műtermékeként kezeljük, integrálva azt a szoftver életciklusával. Ez azt jelenti, hogy a dokumentációt a kódbázis szerves részeként kell kezelni. Ez azt jelenti, hogy ugyanazt a verzióellenőrzést, folyamatos integrációt és tesztelési folyamatokat kell alkalmazni, mint magára a kódra.
Egy tipikus dokumentumban kódbeállításként a dokumentációt egyszerű szöveges fájlokba írja, általában bennük egy könnyű jelölőnyelv, mint a Markdown, HTML vagy reStructuredText. Ezután ugyanabban a tárolóban tárolja, mint a forráskódot. Ez megkönnyíti a szoftver és a dokumentáció változásainak kezelését és nyomon követését. Segít abban is, hogy a dokumentáció naprakész legyen a kód legújabb verziójával.
Miért érdemes a Dokumentumokat kódként használni?
Mielőtt a dokumentumokat kódként kezelték, a dokumentációt gyakran a kódtól különállóként kezelték, és különböző eszközökkel és folyamatokkal hozták létre. Ez a lazább megközelítés gyakran elavult dokumentációhoz és a kóddal való következetlenségekhez vezetett. Számos előnyt élvezhet, ha a dokumentumokat kódszemléletként alkalmazza.
Továbbfejlesztett együttműködés
A Dokumentumok kódként lehetővé teszi az együttműködést a fejlesztők, a műszaki írók és a fejlesztési folyamat egyéb érdekelt felei között. Mivel a kódtárban található a dokumentáció, a különböző felek könnyen hozzájárulhatnak és módosíthatnak. Ez segít abban, hogy a dokumentáció pontos, naprakész és átfogó legyen.
A dokumentáció együttműködésen alapuló megközelítése segít annak biztosításában, hogy az minden lényeges információt tartalmazzon, és pontosan tükrözze a szoftverrendszert, ahogyan azt minden fél értelmezi.
Folyamatautomatizálás és hozzáférhetőség
A docs mint kód másik előnye, hogy lehetővé teszi az automatizált eszközök számára a dokumentáció létrehozását és közzétételét. Egy összeállítási rendszer képes automatikusan előállítani a dokumentáció HTML- vagy PDF-verzióját egyszerű szöveges fájlokból webhelyen vagy belső dokumentációs portálon való közzététel céljából. Ezáltal több érdekelt fél számára elérhetővé válik a dokumentáció.
A dokumentáció létrehozásának és közzétételének folyamatának automatizálásával a docs mint kód segít csökkenteni a dokumentáció karbantartásához és közzétételéhez szükséges időt és erőfeszítést. Lehetővé teszi a fejlesztőcsapatok számára, hogy a szoftver fejlesztésére összpontosítsanak.
Verzióvezérlés
Ha a dokumentációt ugyanabban a kódtárban tárolja, mint a szoftver, megkönnyíti mindkettő változásainak kezelését és nyomon követését.
Te tudod használni verziókezelő rendszerek mint a Git, hogy nyomon kövesse a dokumentáció változásait, és szükség esetén visszatérjen a korábbi verziókhoz. Ez segít abban, hogy a dokumentáció pontos és naprakész legyen, valamint nyomon tudja követni és ellenőrizni tudja a változásokat.
A tipikus dokumentumok kódként munkafolyamat
A tipikus dokumentumok kódként munkafolyamatként az írást, a verziókezelést, az összeállítást és a tárolást foglalják magukban:
Az írási folyamat
Az írási folyamat egy tipikus dokumentum-kód munkafolyamat első szakasza. A legtöbb műszaki írók a dokumentációs mérnökök pedig egyszerű MarkDown-t, AsciiDoc-ot vagy HTML-t használnak. A dokumentációt olyan eszközökkel írják, mint a GitBook és a Redocly, amelyek biztosítják a zökkenőmentes folyamatot.
Verziókontroll a dokumentációhoz
A dokumentáció a kód fejlődésével fejlődik. Szüksége lesz egy kifinomult verziókezelő rendszerre, például a Gitre, a Plastic SCM-re vagy a Subversionra a dokumentáció változásainak nyomon követéséhez az együttműködés és a verziókövetés megkönnyítése érdekében.
A dokumentációkészítés folyamata
Az összeállítási folyamat magában foglalja a dokumentáció feldolgozását és szállítási formátumokba történő összeállítását. Ezek lehetnek HTML, PDF, EPUB vagy mások. A dokumentációs folyamatot általában egyszerűbbé teszik a statikus helygenerátorok, például a Hugo és a Jekyll használatával.
Tárhely és dokumentáció terjesztése
A tárolási vagy terjesztési folyamat általában a dokumentumok utolsó lépése, mint kódolási folyamat. Ez a folyamat biztosítja, hogy a dokumentációt eljuttatják a végfelhasználóhoz, és minden érdekelt fél rendelkezésére álljon. Használhat GitHub vagy GitLab oldalakat vagy egyéni portált a dokumentáció terjesztéséhez az interneten.
Automatizálhatja a Go és a Java dokumentációt a GoDoc és a JavaDoc használatával
A docs mint kódfilozófia forradalmasítja a műszaki dokumentáció írását és kezelését.
Számos programozási nyelv, köztük a Go és a Java, biztosít olyan eszközöket, amelyekkel automatizálható a dokumentáció kód megjegyzésekkel. A Go biztosítja a Godoc eszközt, a Java pedig a JavaDoc-ot.
