Vlákno názorů ke zprávičce Jak napsat dokumentaci k projektu během pár minut?

heezkyyyy. a ja blbec porad datluju dokumentaci rucne :D

Vždyť nejvíc práce je stejně s tím, aby člověk vyjádřil hodnotné informace, které má jinak jen v hlavě a zpřístupnil je ostatním formou dokumentace. A s tím ti žádný program nepomůže. Vygenerovat se dají kvanta textu, ale s jakou hodnotou? Tu hodnotu tam musí dát člověk (do komentářů, zvláštních značek atd.)

Ty nástroje samozřejmě smysl mají, používám JavaDoc a Doxygen, ale bohužel řeší jen formátování/tran­sformaci a ne tu fázi, která je pro hodně programátorů „největší vopruz“ :-D tzn. přepis informací z vlastní hlavy někam jinam :-)

Tu fazi „přepis informací z vlastní hlavy někam jinam“ ma google ve svem planu na rok 2019. Bude to delat automaticky a transparentne :-)

Paradoxne jsme narazili na jiny problem: dobre dokumentace mame spoustu, ale je ji jiz tolik (jenom text je radove ve stovkach MB), ze je nekdy hodne tezke najit nejakou podrobnost. Taky existuji obcasna „temna zakouti“, ktere nejsou up-to-date nebo nemaji dokumentaci vubec. Vzdy to je o tom presvedcit/donutit lidi (model-checking-style anotace by byly fajn, ale v C++ to nema moc smysl).