Leitlinien zur Dokumentation¶
Strukturguide¶
Auf Ebene der Dateien:
rst-Dateien
Dateinamen klein schreiben, englisch Begriffe, Leerzeichen vermeiden, Bindestrich (-) statt Unterstrich (_)
Eine rst-Datei pro Kapitel, möglichst ein englischer Begriff, bsp: configuration.rst
Medien, wie Bilder, etc.
In einen Unterordner media/ des Kapitles ablegen
Benennung der Medien-Dateien:
(unter)kapitelbezeichnung_laufende-nummer_beschreibung-des-dargestellten
(unter)kapitelbezeichnung <– Titel des Kapitels bzw. des Unterkapitels in dem die Medien-Datei verwendet wird
laufende-nummer <– Bilder ihrer Verwendung von oben nach unten fortlaufend durchnummeriert; eine führende Null
beschreibung-des-dargestellten <– Bei Fenstern zum Beispiel der Namen des Fensters
Unterstrich (_) um die drei Felder voneinander abzugrenzen
Beispiel:
../install-on-xcp-ng/media/install-on-xcp-ng_01_network-sketch.png
Hinzugefügte Dateien erben von der vorhergehenden Datei die Laufende-Nummer und diese wird um eine neu aufsteigende Nummerierung ergänzt.
Beispiel:
*1
erste Ergänzung;*2
zweite Ergänzung¶
Medien und Bilder, die in der Dokumentation mehrfach genutzt werden.
Du solltest von diesem Schema abweichen, da diese nur in dem root-Verzeichnis vorhanden sein müssen. Indem auf die laufenden Nummern und Kapitelbezeichnungen verzichtet wird, werden sie als solche kenntlich gemacht. Beispiel wäre die SVG-Grafik follow_arrow.svg die dann mit /media/follow_arrow.svg in der Datei /guided_inst.subst eingebunden wird.
Styleguide¶
Verwende „Du“
Benutze zwei
``backticks``
für URLs, URIs, Dateipfade und Dateinamen und Code im Fließtext (inline)Benutze einen
`backtick`
für das Hervorheben für Benutzernamen, Schaltflächen, besondere Aktionenfür Konsolenbefehle nutze
.. code-block:: console # mein kommando --force output
Für Bilder kann man image oder figure verwenden. Bei figure kann man Bildunterschriften hinzufügen.
.. figure:: media/04_edit-on-github_propose-changes.png :align: center :alt: propose changes Bildunterschriften
Ein Kapitel sollte einen
toctree
enthalten, wenn es mehrere Dateien gibt.Ein Kapitel kann ein Label erhalten bzw. muss eines erhalten wenn es als Sprungziel dienen könnte.
.. _knownbugs-label: Bekannte Fehler ===============
Die Bennung dieser Sprungpunkte sollen immer mit
-label
enden.Mit diesem Sprungpunkt kann man an anderer Stelle auf ihn verweisen
Bitte lies :ref:`hier <knownbugs-label>` nach, welche Fehler bekannt sind.
Um eine Tabelle
Spalte A
Spalte B
Spalte C
Bla
Balbla
Blablabla
Blub
Blubblub
Blubblubblub
Rababa
Rababarababa
Rabararabararabara
einzustellen, nutze folgende einfache Syntax:
=========== ============ ================== Überschrift Überschrift Überschrift Spalte A Spalte B Spalte C =========== ============ ================== Bla Balbla Blablabla Blub Blubblub Blubblubblub Rababa Rababarababa Rabararabararabara =========== ============ ==================