Kürze

29. Oktober 2003, Letzte Änderung: 24. August 2009

Ich gehe in diesem Essay zumeist davon aus, dass die meisten Spezifikationen für Programmierer geschrieben sind. Das muss nicht immer der Fall sein. Eine wichtige Aufgabe ist es, die Zielgruppe zu identifizieren und konsistent für diese Zielgruppe zu schreiben. Wenn man die »falsche« Zielgruppe auswählt, führt das vielleicht noch immer zu einer lesbareren Spezifikation als wenn man »für jeden« zu schreiben versucht.

Vergessen Sie nicht, dass die meisten Leute wenig Zeit haben: Eine Spezifikation mit einem Umfang von 50 Seiten zu lesen, ist sicherlich möglich, auch wenn 15 besser sind, aber wer liest 385 Seiten? Der typische Programmierer wird die ersten 20 Seiten lesen, sich einige weitere Beispiele anschauen und dann sofort anfangen, zu programmieren. Er wird das, was er nicht gelesen hat, durch das ersetzen, wovon er glaubt, es wäre die logische Erweiterung ... Bedauerlicherweise sind Spezifikationen nicht immer logisch; allzu oft sind sie Ergebnis von Kompromissen zwischen den Mitgliedern des Ausschusses. Vermutlich sollte das nicht der Fall sein, aber so ist es in der Praxis nunmal.

Manchmal ist es tatsächlich sinnvoll, eine Spezifikation dadurch zu verkürzen, dass man Erläuterungen entfernt, denn das kann dazu führen, dass mehr Leute sie bis zum Ende lesen werden.

Es gibt auch noch einen weiteren Grund, weshalb das Entfernen von Erklärungen eine gute Sache sein kann: Je mehr Erklärungen es gibt, desto höher die Wahrscheinlichkeit, dass sie sich gegenseitig widersprechen. Es ist besser, Erklärungen und Anmerkungen in ein separates, nicht normatives Dokument auszulagern, oder vielleicht in ein Buch.

Aber entfernen sie nicht die Beispiele! Ein gut gewähltes Beispiel kann oftmals mehrere Absätze an Erklärungen ersetzen. Und darüber hinaus können sie als grober Testfall für neue Implementierungen verwendet werden.

Programmierer finden typischerweise gern heraus, wie Dinge funktionieren, während sie programmieren, eher als englischen Text zu lesen. Das ist ein Paradoxon: Weniger Erläuterungen führen zu besserem Verständnis. Ich glaube, Programmierer mögen Puzzles...

P.S. Stylesheets erlauben alternative Sichten des gleichen Dokuments, zum Beispiel eine mit und eine ohne Beispiele.

Siehe auch

[Lesch00]: Eriksson, Jan Roland; Lesch, Susan; et al.. Friendly Specs. 8 Apr 2000. E-mail thread on www-html [WWWHTML]. URL: http://lists.w3.org/Archives/Public/www-html/2000Apr/0062.html
[WWWHTML]: www-html mailing list. May 1994. Mailing list for discussion of HTML. URL: http://lists.w3.org/Archives/Public/www-html/