// Datei: ./praxis/apt-und-aptitude-mischen/empfehlungen-fuer-dokumentation-und-beispiele.adoc

// Baustelle: Fertig

=== Empfehlungen für Dokumentation und Beispiele ===

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.
// Datei (Ende): ./praxis/apt-und-aptitude-mischen/empfehlungen-fuer-dokumentation-und-beispiele.adoc
