2. Informationen für Autoren und Übersetzer des Mahara Manuals

von Kristina D.C. Hoeppner

Diese Liste wird kontinuierlich während meiner Arbeit am Handbuch fortgeschrieben. Für verschiedene Teile wurden Festlegungen getroffen. Diese sollen zentral sichtbar sein, damit andere Zugriff haben und ich selbst immer wieder darauf zugreifen kann. ;-)

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

2.1. 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.
  • new in Mahara 1.6 Iñaki hat ein Script angepasst, um Screenshot-Text-Kennzeichnungen mit Gimp zu erstellen.
  • 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.

Die meisten Screenshots enthalten Ziffern als Verweise auf den Text:

Example of including a screenshot

Beispiel zum Einbinden eines Screenshots

  1. Die erste Zeile enthält den Pfad zur Datei. * ersetzt die Dateinamenserweiterung und Sphinx wählt die passendste Datei aus. Es sind dadurch unterschiedliche Bilddateiformate oder Screenshots in verschiedenen Formaten möglich.
  2. Die zweite Zeile enthält den Alt-Text, der angezeigt wird wenn man mit der Maus über das Bild fährt oder die Seite mit einem Screenreader aufgerufen wird.
  3. Die dritte Zeile muss leer bleiben. Dies ist der Text, der als Bildbeschreibung unter dem Screenshot angezeigt wird. Bei der PDF-Ausgabe wird diese fortlaufend durchnummeriert.

Bemerkung

Wenn Sie ein Bild inline mit dem Text einbinden wollen und die Ziffernanordnung nicht übernehmen wollen oder können, müssen Sie einen Ersatz anlegen und in die shortcuts.rstext-Datei einfügen.

2.2. Wichtige Hinweise zum Gebrauch

  • Hinweis: für alles was etwas mehr Aufmerksamkeit benötigt
  • Warnung: für alles was mit großer Vorsicht angepackt werden muss
  • auch wichtig: Verweise auf andere Dokumente wenn sie wichtig sind. Verweise auf andere Dokumente können in den Text integriert werden.
  • To-Do’s: für die aktuelle Liste offener Punkte

2.3. Konventionen

  • Jeder Abschnitt, der auf ein Navigationsmenu verweist, beschreibt den Pfad, z.B. Inhalt → Dateien. Am besten kopieren Sie den Pfeil.

  • 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, manage können in den Text eingebunden werden. Der eingegebene Text wird durch die Grafik automatisch ersetzt. Die Ersatzfunktionen stehen in der Datei shortcuts.rstext. Ihr Inhalt wird in jede Datei eingelesen über den Befehl „.. include:: /shortcuts.rstext“ in der ersten Zeile der Datei. Der Verweis auf den „*Bearbeiten*-Button |edit|“ beschreibt was Sie mit dem Button tun können. Übersetzer lassen den Text zwischen den vertikalen Strichen ohne Übersetzung stehen: „|edit|“. Nur derText davor wird übersetzt „*Edit* button“. Achten Sie darauf, dass die Sternchen ohne Leerzeichen vor und hinter dem Text stehen müssen *.

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

  • Neue Funktionen erhalten einen Indexeintrag in der Form „single: New in Mahara 1.6; [the functionality 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.

2.4. Textformatierung

  • Aufzählungslisten erhalten ein * als Symbol zu Beginn jedes Aufzählungspunkts
  • Nummerierte Listen beginnen mit einem #. als Start jedes nummerierten Eintrags.
  • Eine eingerückte Aufzählung (Nummerierung oder Aufzählungspunkt) beginnt mit einer Leerzeile. Danach wird jeder Aufzählungspunkt mit drei Leerzeichen begonnen. Am Ende folgt ebenfalls eine Leerzeile.
  • Hervorgehobener (kursiver) Text beginnt und endet mit einem * wie bei ‚‘hier‘‚. Angezeigt wird dann dies hier.
  • Fetter) Text beginnt und endet mit zwei ** wie bei ‚*‘hie*r‘‚. Angezeigt wird dann dies hier.