Az általam készített alkalmazáshoz dokumentációt ...

Címkék

... szöveges fájlban (txt, doc) írok
22% (63 szavazat)
... markdown, html, chm stb. fájlban írok
15% (42 szavazat)
... valamilyen wiki oldalon írok
16% (47 szavazat)
... programból elérhetően (menüpont, aloldal) írok
3% (10 szavazat)
... csak forráskódban írok
13% (38 szavazat)
... nem írok, mert inkább szóban elmondom a megrendelőnek
2% (6 szavazat)
... nem írok, mert van külön személy erre a cégnél
4% (11 szavazat)
... egyéb formában írok vagy csak az eredmény érdekel
24% (70 szavazat)
Összes szavazat: 287

Hozzászólások

Kulon dokumentacio --> megrendelonek/management reszere
programbol elerheto --> user szamara
forraskodan levo --> fejlesztoknek

Ez 3 teljesen kulonbozo dokumentacio kapasbol, minimalis atfedessel.

--

"You can hide a semi truck in 300 lines of code"

+1

Még annyival egészíteném ki, hogy a forráskód szintjén levő megjegyzések mellé érdemes egy globális, a felépítésről, gondolkodásmódról levő doksit is készíteni, sokat segít, ha nem a kódon belül kell találgatni, hogy most épp melyik modult és mi és honnan és mi alapján tölti be (persze ha úgyis teljes átvétel van, akkor ez se elkerülhető, én csak kisebb hibakeresésre, bővítésre gondolok, hogy hasznos a "térkép"). Viszont ezt gondolom sokan azért se írják meg, mert a javítást-bővítést majd ők végzik, ha meg már nem, akkor ugyan nem érdekli őket a következő programozó lelki üdve.

A kód öndokumentáló. A "mire gondolt a költő" típusú fejlesztőknek szóló dokumentáció a class mellett lehet markdown formátumban, együtt push-olva a repoba. ;)

Az ilyen handleFailEvent() /* This event handles failures */ típusú kommenteknek én nem sok értelmét látom.
--
"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." John F. Woods

Arra gondoltam, hogy nem ártana egy madártávlati kép némelyik programról, nem class szinten, hanem milyen tech-et miért választottunk, milyen pattern-eket miért választottunk, és nagyjából mit merre keress. Minden másra jó a kódba írás, és szerintem is elég a "weird" részek megmagyarázására, de ha nem egy elterjedt felépítésről van szó, sokat segít, ha tudom hol keressem azt a mit.

Millió soros kódon dolgozom. Értelmes class/függvény szervezés, beszédes függvény/változó nevezéktan, és minden elég jól érthető, nincs szükség kommentezésre. Amit a /**/ kommentben le tudnál írni, az egy icipici gondolkodással simán visszafejthető.
--
"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." John F. Woods

Szia,
Amit az előző kommentben leírtál, "madártávlati leírás" az, amire én is gondolok.
Többször volt szerencsém átvenni olyan terméket, ami több belépési ponttal, vagy vezérlés forrással rendelkezik , és tapasztalatból mondom, hogy egy gyors áttekintő mindegyiknél sokat segített volna.
Nem step-by-step, hogy is működik a kód leírásra gondolok, csak arra, hogy miképp kommunikálnak a modulok ( és modulok alatt nem 2 .cpp-re, hanem kimeneti binárisokra, illetve futtató komponensekre gondolok). Míg végigolvasni hasznos a kódot, de sokat segít az értelmezésben, ha egy alapszintű dokumentáció létezik, pl. nem 2 hét megismerni a működését a terméknek, hanem 2 nap.
Míg mondjuk egy szimpla weblapnál/webalkalmazásnál elég lehet a "kód önmagát dokumentálja" szemlélet, egy összetettebb rendszerben már messze áll az elvárható szinttől.
Üdv,
LuiseX

A madártávlati fejlesztőknek szóló funkcionális leírás simán lehet a repoban egy doc könyvtárban struktúrált módon (HTML, Markdown, TeX, stb)
Weird részeknek meg ideális esetben nem kéne a kódban lennie, code review mindenképpen fogja már meg ezeket! Ha ronda haxxolásról van szó, akkor mondjuk, hogy lehet esetleg valami komment mellette, de egy ilyen kódrészlet becsekkelése azonnal szükséges volna, hogy magával vonjon egy "Refactor weird class" taskot, mert nyilvánvaló, hogy design szinten elcseszett dologról lehet szó, különben nem lenne szükség haxxolásra.
--
"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." John F. Woods

Felhasználói, telepítési és üzemeltetési dokumentáció külön file-ban a megrendelő által kért formátumban.
Fejlesztői dokumentációt forrásban (javadoc, vagy xml doc) amiből lehet generálni doxygen-nel emészthetőbb formát ha valakinek kell.

A főnökök szóban tájékoztatva a legfontosabb tulajdonságokról, illetve ezeket rendszerint a szerződés is tartalmazza.

A felhasználó betanítva, menüpontként doksi, illetve egy jegyzetfüzet menüpont,
ahová a felhasználó saját gondolatait feljegyezheti a programmal kapcsolatban.

A forráskódot mindig adom azzal, hogy csak és kizárólag akadályoztatásom esetén (pl meghaltam) és csak és kizárólag szervizelési céllal használható (== a program nem a szerződésben megadott paraméterek szerint működik), 3. félnek át nem adható.

kb így

> Sol omnibus lucet.

Általában PDF, de a Wiki is jó dolog, persze ott van PDF-ben a Wiki is, mert valaki azt jobban bírja, ha külön is meg tudja nyitni, mert az olyan professzionális.

--
A főnököm mindig megtartja amit ígér, ha pénzt ígér azt is!

Magán tudásbázis --> Wiki
Hivatalos céges, benyújtható --> .doc, mert azt szeretik

Wiki és/vagy programból elérhető és/vagy forráskódban.

Nem írok, mert a felhasználóim gondolatolvasók.

Csak akkor írok, ha a megrendelő igényli és akkor doc-ban, konvertálva PDF-be.
Illetve a forráskódot szinte mindig szoktam kommentálni, magam, vagy más fejlesztők számára.

ODT-ben (LibreOffice) írok felhasználói kézikönyvet, saját konverter átalakítja CHM helppé és nyomtatható PDF-fé.

forraskodba irt Doxygen, az melyik lehetoseg? :D

Devel fele Confluence wiki. Ebben vannak:

- a user story-k, acceptance criteria-kkal, érintett képernyőkkel és szakindoklással (mindjárt megérted, miért)
- a flow ábrák
- a scenario-k
- az adatdefiníciók
- képernyőnkénti bontásban
-- mi miért van úgy, visszautalás user story-ra
-- pszeudokód minden interakcióra
-- változó életciklus kezelések
-- szélsőesetek, hibaüzenetek

Confluence-ben kommentelhető minden szó, a képeken komment pont helyezhető el, a képek nagyíthatóak (differenciálspecinél, amikor a régi és az új képernyő egymás mellett van, nagyon hasznos), ez az utóbbi amit a gDocs nem tud.

Természetesen a vezetők, megrendelők kapnak pdf-et is, de a technikai emberek a kommentelhetőség meg az "egy, mindig aktualizált változat" miatt accountot kapnak.

Nem ez az egyetlen doksink (sok projektmenedzsment zajlik belül marvel prototípusok kommentjeiként pl, azon zajlik a UX-UI átadás nagy része), de a programozók fele minden ebben van.

DITA

Egyébként van rá külön személy a cégnél. Ők megtanítottak minket DITA-ban doksi inputot adni, mi megtanítottuk őket git-et használni. Azóta a fejlesztők pull request-ben adják a nyers doksit, a doksírók meg összeszerkesztik (illetve lefordítják angolról angolra, és megpróbálják érthetőre átírni :).
---
Régóta vágyok én, az androidok mezonkincsére már!

Van wikin is, a menedzsmentnek csak az, a diagramok is ott vannak és a legtöbb kapcsolódó dolog. Meg van docstringből generált dokumentáció is. Ha az Doxygen, akkor általában van call/caller gráf is, ha Sphinx akkor nincs.

Kb 1:1:1:1 aranyban: latex+pdf, --(long-)help | help2man | man, wiki, semmi (szóban, sehogy, oldd meg, stb)