12.4. Empfehlungen für Dokumentation und Beispiele

Zurück		Weiter

Stöbern Sie nach Beispielen zur Paketverwaltung oder auch in der Dokumentation zu komplexeren Softwarepaketen, wird der stete Wechsel und die Vermischung von dpkg, APT und aptitude offenkundig. Bislang hat sich dazu noch kein Standard durchgesetzt, welches der vorgenannten Werkzeuge zur Installation genutzt oder empfohlen wird. Jeder Entwickler und Autor folgt an dieser Stelle seinen eigenen Präferenzen.

Verfassen Sie selbst Dokumentation, Beispiele oder Anleitungen, raten wir Ihnen zu folgendem Vorgehen:

geben Sie die verwendeten Programme stets in identischer Art und Weise an. Das betrifft insbesondere die Groß- und Kleinschreibung bzgl. APT und apt, da sonst Gefahr zur Verwirrung besteht, welches Werkzeug tatsächlich gemeint ist.
geben Sie bei den Optionen und Schaltern sowohl die genutzte Kurz- als auch die Langversion an, sofern diese existieren und bekannt sind. Erklären Sie zusätzlich, warum Sie die von Ihnen verwendeten Optionen nutzen und diese in der genannten Reihenfolge Verwendung finden.

Mit diesen Schritten steigt das Verständnis des Kommandoaufrufs und vereinfacht es nicht nur Einsteigern, vorab zu verstehen, was da passieren soll. Der vollständige Aufruf mit Beschreibung klärt Missverständnisse und hilft Ihnen auch dabei, Fehler zu vermeiden.

Bei der Benennung und Auswahl der Werkzeuge spielen Gewohnheit und die Faulheit beim Tippen des Aufrufs eine Rolle. Nutzen Sie einen expliziten Aufruf, der exakt so funktioniert und nicht anders, hilft neben einem Hinweis auch ein wenig Hintergrundinformation zum Aufruf. Dazu zählen insbesondere Seiteneffekte, von denen Sie wissen und die Sie durch die spezifischen Parameter jedoch vermeiden möchten. Ein Verweis auf Alternativen und zusätzliche Dokumentation rundet den Text ab.