Jak vývojářům zpříjemnit psaní dokumentace

Vývojář Qt a KDE Aaron Seigo píše ve svém blogu o tom, jak programátorům zpříjemnit psaní dokumentace, kterému se většinou obloukem vyhýbají. Jeden z možných způsobů, který u Aarona zafungoval, je použití wiki.

13.8.2010 18:03 | Robert Krátký | Zajímavý článek

Komentáře

[Marián Kyral]

který u Aaronu zafungoval

Cože?

[Robert Krátký]

Sorry, překlep.

[void]

Psaní čehokoli do wiki nedoporučuji, pokud zbytek týmu nedodržuje: (1) stejnou kvalitu dokumentace jako vy; (2) stejné formální konvence jako vy. Máloco dokáže dokumentaristu naštvat víc než poničení dokumentace nějakým nýmandem. (Tento problém nastává zejméne tehdy, je-li wiki veřejně editovatelná.)

[zulu]

Taky si občas říkám, že raději nic než toto. Ale obecně asi raději něco než nic.

[Josef Kufner]

Tak ono nemusí být veřejně editovatelná, ono hodně pomůže i když je jen pro vývojový tým. Wiki totiž má asi nejnižší práh, který je nutné překonat, pro provedení změn.

[Luboš Doležel (Doli)]

Obzvlášť programátoři mají navíc blbý návyk všechen text ve wiki nacpat do PRE bloku, což je příšernost.

[Sten]

Cože? Wiki rozhodně není dobrý způsob (vyzkoušeno v docela velké firmě), dokumentace velmi rychle zastará a změny málokdo udržuje, navíc Wiki se strašně blbě propojuje s verzovacím systémem vývoje software, takže třeba při branchování najednou Wiki popisuje něco, co vůbec neexistuje, dokud se všechny branche nezmergují. A co teprve, pokud se nějaká branch zahodí! Nejúčinnější je Doxygen ve spojení s kontrolami při commitu (nesmí projít nic nezdokumentovaného)

Na druhou stranu, něco jako Doxygen s Wiki syntaxí bych opravdu uvítal, ta syntaxe Doxygenu není moc přehledná