2. Informationen für Dokumentationsschreiber

Dies ist eine fortlaufend während der Arbeit an der Dokumentation entstandene Liste von Kristina Höppner. Sie enthält die Beschreibung einiger Konventionen und Vorgehensweisen. Sie sollen zentral abgelegt werden, damit andere darauf zugreifen können und die Liste weiter gepflegt werden kann. Maßgeblich ist die englische Version dieses Kapitels.

Die Reihenfolge der Einträge in dieser Liste ist zufällig.

  • Bildschirmfotos

    • werden über die Bild-Anweisung (‚figure‘) eingebunden
    • enthalten immer ‚Alt‘-Texte und Bildbeschreibungen. Die letztgenannten werden im PDF-Export durchnummeriert. Sie werden vom Text abgesetzt.
    • werden grundsätzlich vor einer Aufzählung der Schritt-für-Schritt-Anleitung platziert
    • sollten so wenige Schritte wie möglich enthalten und genau die Schritte beschreiben, die im Screenshot abgebildet sind. Dadurch können sie einfacher ausgetauscht und übersetzt werden. Übersetzer können daher im ersten Schritt die Texte übersetzen und müssen nicht zwangsläufig auch die Bilder austauschen.
    • wurden mit Shutter in Ubuntu erstellt. Es ist gut geeignet, um die Schrittfolge im Bild mit Zahlen zu kennzeichnen (callouts). Es kann natürlich auch jede andere Screenshot-Software verwandt werden. Es empfiehlt sich die eingefügten Zahlen zu verwenden, um Ähnlichkeit zu erreichen. Die Farbe ist #4C711D.
    • enthalten Ziffern, die die Reihenfolge der Arbeitsschritte verdeutlichen und im Text unter dem Bild beschrieben werden.
    • soll nur den erforderlichen Bildbereich zeigen und nicht den gesamten Bildschirm, wenn dies nicht unbedingt erforderlich ist.

  • Es werden folgende Warnhinweise verwandt:

    • Notiz: für alles, was etwas mehr Aufmerksamkeit erfahren soll
    • Warnung: für alle Dinge, die mit besonderer Vorsicht behandelt werden sollen
    • Siehe auch: als Querverweis auf andere Dokumente, die besonders empfohlen oder benötigt werden. Verweise auf andere Dokumente können auch im fortlaufenden Text verlinkt werden.
    • Todo: alles, was auf eine fortlaufende Erledigungsliste gehört.

  • Buttons wie Speichern oder Kopieren und die Portfolioauswahl wie Inhalt, Portfolio usw, werden im Text hervorgehoben mit Hilfe eines einzelnen ‚Sternchen‘ (‚*‘)

  • Kleine Buttons wie [edit] oder [manage] können in den Text eingefügt werden. Sie werden durch einen Platzhalter hinzugefügt. In der Datei shortcuts.rstext werden sie hinterlegt. Dieser wird am Beginn jeder Datei eingebunden (aufgerufen) in dem es Ersetzungen gibt. Der Verweis erfolgt über folgende Formatierung: „Bearbeiten-Button edit„. Er bezeichnet genau, was an der Stelle getan werden soll.

  • Ein Index-Eintrag sollte für jeden Abschnitt erzeugt werden.

  • Neue Funktionen erhalten einen eigenen Index-Eintrag in der Form „single: New in Mahara 1.5; [the thing that is new]“.

  • Lange Abschnitte sollten auf mehrere Seiten aufgeteilt werden, um das Bearbeiten zu vereinfachen

  • reStructuredText hat keine vordefinierte hierarchische Überschriftenstruktur. Sie werden in jeder Datei neu definiert. Um ein einheitliches Gestaltungsbild zu erzielen, werden folgende Vorgaben definiert:

    • Überschrift 1, z.B. 1.: ===============
    • Überschrift 2, z.B. 1.1.: —————
    • Überschrift 3, z.B. 1.1.1.: ~~~~~~~~~~~~~~~
    • Überschrift 4, z.B. 1.1.1.1.: ^^^^^^^^^^^^^^^

  • Weitere Überschriftenebenen nach h4 sollten unbedingt vermieden werden, da sie nicht mehr der Übersichtlichkeit dienen.