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.

  • Screenshots are placed as figures and always include alt text and a figure description. The latter will receive numbering in the PDF export.

  • 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‘ (‚*‘)

  • Little buttons can be included in the text.

  • Screenshots of Mahara sections are not made inline, but receive the „figure“ directive. They always have an alt tag and also a brief description which will show up below the image and is numbered in LaTeX PDF.

  • Screenshots should have as little instructions as possible about the steps that are to be taken in them. Preferably, only the step numbers so that they can be exchanged more easily and the text of the steps is translatable because it is text and not part of the image. That could also mean that translators can translate the steps but don’t immediately have to change the screenshot.

  • Inline images that are refered to in the textsuch as edit should be included as shortcuts with the reference at the bottom of the page.

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

  • 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.

  • I create screenshots with Shutter in Ubuntu. It is easy to add the callouts which indicate the steps to take. However, any other screenshot software can be used. Preferably, the callouts look similarly. The color is #4C711D.

  • The callouts in the screenshots refer to the steps that need to be taken.

  • Screenshots should only show the necessary area and not the entire screen or URL address bars etc. where not necessary.