Jó fejlesztői dokumentációra példa

 ( asch | 2011. április 12., kedd - 12:24 )

Sziasztok!

A dokumentáció egy óriási feladat, amit nehéz jól csinálni. Hogy tanuljak szeretnék jó példákat megnézni.

A kérdés tehát az, hogy ismertek-e olyan projekteket, aminek jó fejlesztői dokumentációja van, tehát érdemes néhány ötletet, módszert ellesni belőle?

Olyan projektek érdekelnek, amiknek a dokumentációja ingyenesen hozzáférhető, tehát praktikusan szabad szoftverek jönnek számításba.

Hozzászólás megjelenítési lehetőségek

A választott hozzászólás megjelenítési mód a „Beállítás” gombbal rögzíthető.

Én értem félre a kérdést? Ezek szerintem fejlesztőknek szánt felhasználói dokumentációk.


alias killall='echo "Wenn ist das Nunstück git und Slotermeyer? Ja. Beiherhund das Oder die Flipperwaldt gersput." | espeak -vde' #That's not funny.

A dokumentáció egy óriási feladat, amit nehéz jól csinálni. Hogy tanuljak szeretnék jó példákat megnézni.

A kérdés tehát az, hogy ismertek-e olyan projekteket, aminek jó fejlesztői dokumentációja van, tehát érdemes néhány ötletet, módszert ellesni belőle?

Én erre válaszoltam.
--
http://www.naszta.hu

+1

Ha a felhasználók fejlesztők, sokan fejlesztői dokumentációnak tartják a felhasználóit, pedig szerintem sem az.

Na, az msdn az valami, talán még etalon is lehet api dokumentációra.

--
"SzAM-7 -es, tudjátok amivel a Mirage-okat szokták lelőni" - Robi.

Eleg regi, meg nem biztos, hogy pont erre gondoltal, de par honapja talaltam, es nekem tetszett ez a par reszes iras:
http://www.joelonsoftware.com/articles/fog0000000036.html

Joel Spolsky tippjeire +1.

Alapvetően minél kevesebb marketing duma, és minél több, jól elkülönített, kiemelt KONKRÉT PÉLDA kell bele, az a legjobb. Egy jól megírt példa többet mond ezer magyarázatnál.
--
Coding for fun. ;)

Spring framework doksik: Reference manual + javadoc
Hibernate doksik: Reference manual + javadoc

Itt egy elég nehéz témáról van szó és az a cél, hogy minél jobb legyen a dokumentáció is http://exciting-code.org

http://www.mjmwired.net/kernel/Documentation/stable_api_nonsense.txt

--
NetBSD - Simplicity is prerequisite for reliability

ahahah, már vártam :-)

--
"SzAM-7 -es, tudjátok amivel a Mirage-okat szokták lelőni" - Robi.

Mindenkinek mas jon be, nekem pl a Perldoc azert, mert azon tul hogy referenciakent es bemutatonak egyarant alkalmas, tokig van olyan utalasokkal, hogy "ha azt akarod, hogy... akkor ...".

Általában a interpreter nyelvek dokumentációi(python, java) meg szoktak felelni az igényeimnek. Ha már itt tartunk nem értem hogy a natív lib-ekhez miért nem találok soha semmi értelmeset, néhány hevenyészett README fájlon kívül.

A java nem interpreterrel fut rendszerint, hanem VM -ben.
Nagyon más.

Én ezekben látom az okokat:
* Ugyanazt sokkal több kódban oldod meg, és sokkal több részletet kellene dokumentálni
* Nincsen jó minőségű és egységesen elfogadott dokumentáció generáló és meglétét ellenőrző rendszer
* Nincs mögöttük olyan cég (gondolom főleg Linuxos libekre gondolsz), ami standarddá tenné, hogy márpedig kell dokumentáció, addig nem lehet kiadni.

Ennel mar csak az odadobott doxygen-es szemetek rosszabbak :(
Persze lehet azt is tisztessegesen csinalni, de keves olyat lattam.