[API's] Normen voor goede documentatie

[Canis Lupus]

Voor school gaan we met een projectgroep een vergelijkend onderzoek doen [tussen Direct3D en OpenGL].
Nu ga ik me concentreren op de documentatie van de twee API's.
Ik heb genoeg documentatie zelf, maar waar ik dus naar op zoek ben zijn enkele normen/voorwaarden/aandachtspunten voor goede documentatie bij software/API's.
Ik heb me al suf gezocht met google, maar kan niet echt iets bruikbaars vinden.

Samengevat: Wat maak documentatie GOEDE documentatie ?

Heeft iemand een goede link of zelf enkele tips?
Alvast heel erg bedankt!

[Dennis]

offtopic:
Wat cool dat je dat soort dingen op school krijgt

Verder, heb je voor Direct3D al MSDN geprobeert ?
http://msdn.microsoft.com

of direct zoeken:
Lange url

[Canis Lupus]

Hmm, ik bedenk me nu dat mijn formulering idd niet helemaal duidelijk is [ga ik nu aanpassen ]

Ik heb dus genoeg documentatie [idd van msdn.microsoft.com en opengl.org], maar ik ben op zoek naar criteria waarop ik die 2 kan vergelijken [concentrerend op de documentatie dan]


Alavst heel erg bedankt!

[Janoz]

Ik zou ook bij wat onafhankelijkere sites kijken voor info. Bij msdn waarschijnlijk nix dan goeds over directX, maar als je het de maker van quake vraagt (ben ff zijn naam kwijt) heeft ie d'r heel andere dingen over te zeggen.. Hetzelfde zal waarschijnlijk ook wel op gaan voor OpenGL..

[MrBrown]

Ik denk eerder dat hij bedoelt dat hij info zoekt over wat documentatie goede documentatie maakt.

Uhm, ik weet dat trouwens ook niet precies, maar misschien moet je het googlelen eens over een andere boeg gooien en zoeken naar hoe je goede documentatie schrijft, en daar de documentatie die je hebt aan toetsen...

[Banpei]

* Banpei denk dat als je beide API's gaat vergelijken dat je dan voornamelijk moet kijken hoe gemakkelijk het te proggen is, schaalbaarheid (openGL is multiplatform bijv.) en uit welke tijd het stamt en hoe het gericht is op de toekomst...

[Canis Lupus]

Op maandag 01 oktober 2001 10:08 schreef MrBrown het volgende:
Ik denk eerder dat hij bedoelt dat hij info zoekt over wat documentatie goede documentatie maakt.

Uhm, ik weet dat trouwens ook niet precies, maar misschien moet je het googlelen eens over een andere boeg gooien en zoeken naar hoe je goede documentatie schrijft, en daar de documentatie die je hebt aan toetsen...

Je slaat de spijker op zijn kop MrBrown !!!
Ik zal binnenkort nog een keer intensief gaan zoeken met Google, maar dit is dus wel precies waar ik naar op zoek ben!
Dus als iemand een link of info heeft... graag!

En Banpei, we concentreren ons idd op deze punten. Ik neem dan de documentatie onder mijn hoede..

[mbravenboer]

Javadoc wordt over het algemeen als een interessant systeem gezien. Op de home-page hiervan kan je behoorlijk wat info vinden:

http://java.sun.com/j2se/javadoc/

Specifiek kan je eens kijken naar dit:

http://java.sun.com/j2se/javadoc/writingapispecs/index.html

Ik denk dat je hiermee een heel eind komt

[Canis Lupus]

Op maandag 01 oktober 2001 11:52 schreef mbravenboer het volgende:
Javadoc wordt over het algemeen als een interessant systeem gezien. Op de home-page hiervan kan je behoorlijk wat info vinden:

http://java.sun.com/j2se/javadoc/

Ik denk dat je hiermee een heel eind komt

Ik ga hier vanavond eens rustig naar kijken, bedankt voor de info!!

Tips blijven welkom!

[Canis Lupus]

*KICK*

[kvdveer]

imho bevat goede documentatie de volgende items:
* Duidelijke inhoudsopgave
* Beschrijving van alle klassen en methoden (een beschrijving langer dan ("This class handles color management")
* Bij iedere methode een voorbeeldje van wat je er mee kunt
* VEEL tutorials en codevoorbeelden
* Nog meer tutorials
* Links naar gerelateerde websites
* Veel informatie dubbel: dwz niet continu: ("Zie Class RBGColor voor uitleg over kleur management")
* Cross links (veel en relevant)