A napokban érdekes beszélgetések sorozata alakult ki a projektünkben, ami jól mintázta, hogy a különböző háttérből jövő kollégák néha ugyanazt a kifejezést eltérő dolgokra használják.
Az input annyi volt, hogy a szomszéd projektben a dokumentáción dolgoznak, nézzünk körbe mi is, hogy mit szeretnénk használni.
A vita a dokumentáción volt, hárman háromféleképpen értelmeztük. Én a kódolásból jöttem, nekem ez programdokumentációt jelentett, az egyik kolléga érdekes rendszerleírásokat talált Word formában, a második kolléga szerint az úgynevezett működési kézikönyvről volt szó, amiben kvázi leírják, hogy milyen technikai háttérrel, adatbázis installal satöbbi lehet a programot fejleszthetővé és futtathatóvá tenni.
Ennek kapcsán hallottam a legérdekesebb kritikát a dokumnetálással kapcsolatban: kódírás közben az illetékes elvtárs nem fog kódban dokumentálni, ámde a változásokat majd átvezeti egy Word dokumentbe. Ugyanez a kolléga pár nappal később bajba került, mert nem a megfelelő szerveren végzett Bugfixet, és mikor élesítésre került sor, nem tudta, hogy mit kellene tenni.
Én a magam részéről az API dokumentálás szükségessége mellett vagyok, és nem általok privát projektekben is JavaDoc-ot (vagy újabban PHPDoc-ot) használni e célra. A legtöbb esetben ez a fajta doksi számomra elegendő. Ami kimarad, és amire időnként mégis csak szükség van, az az adatbázis dokumentálása. Ugyan többnyire elég a create table statement-eket lementeni, néha azonban tényleg nem árt pár soros hozzászólást tenni ahhoz, hogy mit miért csináltam.
Mivel a kérdés még nem dőlt el, érdekelne a Ti véleményetek! Szoktatok-e dokumentálni és ha igen, hogyan?
A kódba írt dokumentáció mindenképpen szükséges (JavaDoc/PHPDoc) ez a fejlesztési dokumentáció része lesz (a specifikációkkal, tervekkel és adatbázis séma dokumentációval együtt) ezen felül készül a szokásos felhasználói és üzemeltetési dokumentáció (Wordben/LibreOfficeban illetve kísérleti jelleggel Markdownban), ez utóbbiak PDF-ben kerülnek leszállításra egyelőre, de jobb lenne ezeket is valami interaktívabb formára hozni, képek helyett kis videokkal, animgifekkel illusztrálni, erre általában valami wiki szokott lenni a válasz, de az valamiért nekünk sosem volt sikeres… Talán teszünk egy próbát a Confluence-szel.
Köszi, megnyugtat, hogy nem én voltam a “sík hülye” a témában, amikor lecsaptam a az API doksi szükségességére. (nem éreztem magam annak, csak furán jött ki az ellenkezés, hogy arra nincs szükség…)
A user doksit direkt hagytam ki a felsorolásból, az a program élesítésénél nálunk egy “must have” 🙂 Confluence-t használtam, én nem szeretem annyira a wiki markup-ját, mint pl. a mediawiki-ét, de megszokható, ha meg akarja szokni az ember. Nálunk helyből azt supportálja a cég (meg JIRA-t bugtrackinghez), úgyhogy nem volt más választás. Viszont a wiki belső okoskodásnak/okosodásnak használjuk (használom).
Dokumentáció ? Maximum egy Changelog.txt… 😉