Markdown specifikáció - Ti milyen dokumentációs toolt használtok?

Fejlesztés

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 :-)

  • 6200 megtekintés

( enpassant v | 2014. 09. 04., cs – 12:35 )

Szerintem elég jó a kedvenc "sztekked"! :)

Mi a cégnél nem használunk Markdown-t (pedig jó volna), hanem helyette sima txt-t, szükség esetén ebből kerül át a szöveg a "Word"-be, ami nálunk jellemzően LibreOffice.

"Mivel biztos fel fog merülni: a LaTeX-et bár ismerem, kerülöm. De ez már egy másik téma :-)"

Nekünk van egy félkész xml szerkesztőnk, amivel böngészőben lehet WYSIWYG-ben (a végső html kinézetében) szinte tetszőleges struktúrájú xml-t szerkeszteni.
Ez is alkalmas lenne doksi írásra, ami nagy előnye lenne, hogy az xml-ből aztán bármi kinyerhető: html, pdf, latex, adatbázis script-ek, ...
Ezek ki is lettek próbálva, de sajnos nem lett odáig fejlesztve, hogy akár magunk is használni tudjuk.
Jó volna egyszer termékké fejleszteni :)

( zoner | 2014. 09. 04., cs – 12:43 )

Dokuwiki.

Tud exportalni PDF-be, Word-be, kisebb vallalkozasoknak, egyszemelyes fejlesztoknek tokeletes. Sajnos nem Markdown, de ertheto a markup.

Nekünk vegyesen van word, latex, wiki, mantis entry, text doksik svn-be mentve... igény volna egy nagy egységesítésre.

Nekem egyébként a szövegfájl valami formátumban jön be a legjobban, mint a Markdown, de valószínűleg megfelelő minőségű manualokat nagyon nehéz lenne benne összerakni.

( kmARC v | 2014. 09. 05., p – 11:48 )

Első, és utolsó bump. Úgy látszik, másokat nem mozgat annyira meg ez a téma.

( kroozo v | 2014. 09. 05., p – 17:36 )

Akkor még bedobom neked, én a gitittel szemezgetek egy ideje (ill fű alatt használom is). Kissé fapad, de egész jópofi. Alapból markdown wiki, de pandoc van mögötte, uh tud mindenfélét exportálni (meg a forrás is lehet nem csak markdown emiatt), beleheggeltem valami plugin lemásolásával, hogy tudjon inline értelmezni graphvizt meg blockdiagot (aminek tök jó kis cuccai vannak egyszerű rajzolgatásra).

Ill az egész mögött git (vagy asszem lehet még darcs) van, ennek minden előnyével.

( asusu | 2014. 09. 05., p – 20:26 )

* Kisebb dolgokhoz (pl. README, INSTALL, blog :) Markdown
* Komolyabb dolgokhoz: reStructuredText (Sphinx-szel meghajtva)

( BaT | 2014. 09. 05., p – 21:37 )

Nálunk github féle markdown van ilyesmire, révén githubon dolgozunk. :) Én szeretem, az általam ismert hasonló formátumok közül (asciidoc, textile) a legértelmesebb (habár nem túl feature ritch), illetve elég elterjedt is. A lényeg úgyis az, hogy a lehető legkevesebb efforttal lehessen helyes kimenetet előállító dokumentumot gyártani, amihez az se árt, ha a támogatott feature-öket könnyű fejben tartani (máskülönben nem lennének használva akkor sem, amikor van értelme).