A napokban kellett dönteni egy projektben arról, mivel írjuk a dokumentációt. Közben körbejárta az Internetet a hír, hogy páran összefogtak, és megalkották a Markdown specifikációt: http://standardmarkdown.com/
Egyrészt ennek örülünk, és köszönjük az erőfeszítéseket. Másrészt viszont kicsit szomorkodunk, hogy olyan cool dolgok, mint pl. a táblázatok a MarkdownExtrából nem kerültek be.
:-(
Mi végül Markdown/ReText kombónál maradunk, viszont érdekelne, hogy (főlkeg szoftveres projektben, tehát ahol akár a developer is néha dokumentációt kényszerül írni), mit használtok? Gondolok itt az egész spektrumra: Egy README-től kezdve a fejlesztői doksin át a User Guide-ig mindenre. Természetesen nem a kód/API doksira gondolok, azt alapértelmezettnek veszem, hogy javadoc/jsdoc/doxygen/etc van.
Szóval: ti mire, mit használtok?
Az én személyes kedvenc sztekkem a következő:
Markdown(Extra). Szeretem, ha egy egyszerű szövegszerkesztővel lehet írni a doksit, a forrásfában csak ilyent engednék meg. Táblázat feature kicsit macerának tűnik bővíthetőség szempontjából, de vannak erre is jó megoldások (https://github.com/godlygeek/tabular).
Külön, doksi repóba feltöltve (ahogy pl. githubon is), kényelmes a fejlesztőknek is. Személyes tapasztalat: Ha nem tudja a dev. azonnal megnézni böngészőben, akkor az a doksi _szinte_ nem is létezik. Ha nem tudja _szerkeszteni_ böngészőben: akkor egyáltalán nem létezik. Egy projektben egyszer docbookban (xml) kellett doksit írni. Senkinek nem volt fogalma sem, hol áll a fejlesztés és a szoftver... vagy éppen maga a dokumentáció...
(Szinte bármilyen) wiki. A fenti problémát pont a wiki küszöböli ki. Még jobb, ha (megintcsak a github/gitlab példájánál maradva) a wiki-t egyből gitbe menti, a legszueprebb, ha pedig rögtön Markdown-ban írhatjuk :-)
A wikis megoldáshoz mindenképpen szeretek belőni egy pdf exportert: a managereknek, product ownernek jót tesz, ha akár kinyomtathatja, és nézegetheti, és persze akkor kap egy oldalszámot is. Hátránya a wikinek a hierarchia hiánya: ez konvenciókkal kiküszöbölhető.
Word. WTF? Ezt én sem gondolhatom komolyan. Néha azonban olyan (főleg nagyvállalati) projektben találjuk magunkat, amikor nagyonfenszi, régimódi KÉZIKÖNYV kell.
Bár a Markdown->wiki->PDF járható útnak tűnik (én továbbra is talán ezt preferálnám), de be kell látni: a kézikönyvet már remélhetőleg nem én fogom írni, hanem az erre felvett technical writer. Ő pedig ne egy mancinéni legyen, aki egérrel kijelölve 29,3-as betűméretre állít, hanem ismerje a nagy office programok minden legtöbb csínját-bínját (template alapú formázások, referenciák, bibliográfia, etc.)
Mivel biztos fel fog merülni: a LaTeX-et bár ismerem, kerülöm. De ez már egy másik téma :-)