dedlfix: JSDoc Tags gleich? widersprüchlich?

Beitrag lesen

Tach!

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. 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.

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. Oder wo man gegebenenfalls die Information findet, die das Programm benötigt.

dedlfix.