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.

    propose changes

    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 Aktionen

  • fü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
    =========== ============ ==================