JSDoc Tags gleich? widersprüchlich?

[Der Martin]

Hallo,

Mir sind aber schon öfters Softwarepakete in die Hände gefallen, wo eine derartige, automatisch erstellte Dokomentation alles war. Ist ja auch verführerisch, dieses beruhigende Gefühl, man hätte schon was getan.

Das ist aber ein allgemeines Problem und keins der *Doc-Systeme.

korrekt: Man benutzt ein Hilfsmittel, das einen glauben lässt, damit sei alles getan. Etwa so, als würde man ein kleines elektronisches Gadget anbieten, und die Bedienungsanleitung erschöpft sich in einer Abbildung mit zwei, drei Worten zu jeder Taste.

Als Entwickler kennt man sein Produkt in- und auswändig und weiß, wie die Dinge funktionieren. Die anscheinend meisten tun sich jedoch nicht nur dabei sehr schwer, Dinge aus anderen Perspektiven zu betrachten und können sich nicht so richtig vorstellen, welche Informationen ein Außenstehender benötigt.

Das ist IMO wieder ein anderes Problem: Die Unfähigkeit, Dinge aus der Perspektive eines Uneingeweihten zu betrachten.

Telefonnummer
|___________________________________________________________________|
Geben Sie eine Telefonnummer ein.

Das ist die Art Dokumentation, die man als Anwender nicht braucht. Es ist offensichtlich, dass man in das Feld „Telefonnummer“ eine Telefonnummer eingeben soll. Es ist jedoch nicht offensichtlich, welche Schreibweise das Programm erwartet.

Genau. Oder wessen Telefonnummer. ;-)

Ciao,
 Martin