How to Participate in Documentation

Aus Mandriva Community Wiki

Als erstes solltest du

• dich in die Mailingliste eintragen,
• eine lokale Kopie der Quellen anlegen.

Inhaltsverzeichnis 1 Arbeitsprinzipien 2 Die verschiedenen Hilfsmittel 3 Projektmanagement Schnittstelle (SvnNav) 4 Arbeitsfluss 5 Anweisungen für Übersetzer

Arbeitsprinzipien

Das ganze System basiert auf Scripte, die automatisch gestartet werden wann immer Änderungen an der SVN Quelle übergeben werden.

1. Bei Änderungen überprüft das System ob die Änderung gültig ist und alle Abhängigkeiten verfügbar sind
   • Wenn alles in Ordnung ist wird der modifizierte Inhalt in eine spezielle, versteckte "Validierungs"-Quelle verschoben
   • Ansonsten wird die Datei als ungültig deklariert und eine Meldung erscheint in dem SvnNac Interface (siehe unten)
2. Wenn die Dateien validiert wurden, werden alle möglichen Informationen extrahiert: Arbeitsablauf, Abhängigkeiten, etc.
3. Danach geht es weiter zu den Abhängigkeitsbaum um zu prüfen welche Publikationen (HTML oder PDF) von dieses Änderungen betroffen sind und regeneriert diese Publikationen in [1]

Note: After a commit you can follow the processing by looking at http://neodoc.mandrivalinux.com/

Die verschiedenen Hilfsmittel

Du brauchst einen DocBook Editor, beispielsweise:

• Emacs + nxml Modi
• XXE dessen freie Personal Edition zum Bearbeiten freier Dokumentationen genutzt werden darf
• Conglomerate ist für Mandriva verfügbar aber nicht vollständig getestet wurde

Um Schemata im SVG Format zu bearbeiten, benötigst du Inkscape.

Projektmanagement Schnittstelle (SvnNav)

Die SvnNav Schnittstelle erlaubt es dir durch die Quellen zu navigieren und eine Auswahl nützlicher Informationen für Schreiber, Übersetzer und Projektleiter an zuzeigen:

Zu jedem Ordner findest du eine Liste von enthaltener Dateien mit jeweiligen Informationen:

• als DocBook validierte Dateien ohne fehlende Abhängigkeiten (wie zum Beispiel Bilder) im 'Status column
• Welche die current task (derzeitige Aufgabe) ist, die zu erledigen ist.

Beim Anklicken einer Datei wird eine detaillierte Statusseite mit folgenden Informationen angezeigt:

• Einsicht der Gültigkeits- und Abhängigkeitsberichten im Problemfall
• Liste der Übersetzungen dieses Modules, falls verwendbar
• Verknüpfung zur originalen Datei, falls es sich um eine Übersetzung handelt
• Verknüpfung zu der Anderungsseite hinsichtlich früherer Versionen, falls vorhanden
• Verknüpfung zur Struktur Diff mit originalem Modul, falls vorhanden
• kompletter Arbeitsfluss
• Log der Änderungen
• Liste der Abhängigkeiten (XML Dateien oder Bilder die in der Datei enthalten sind)
• Liste der Objekte, die dieses Objekt verwenden (umgekehrte Abhängigkeiten)

All das erlaubt es dir durch den Verzeichnis- oder Abhängigkeitsbaum zu navigieren, was es möglich macht alle XML Module zu prüfen, die zum Beispiel von einem Dokument genutzt werden.

Arbeitsfluss

Der Arbeitsfluss (workflow) beruht auf einem sehr einfachen System, basierend auf dem <revhistory> Element von DocBook.

Wenn du einen Arbeitsfluss in einem XML Modul haben möchtest, musst du lediglich ein spezielles revhistory Element am Anfang des <info> Element des Modules ergänzen.

Als Beispiel:

<?xml version="1.0" encoding="utf-8"?>
<book xmlns="http://docbook.org/ns/docbook" xmlns:xi="http://www.w3.org/2001/XInclude"xmlns:ns="http://docbook.org/ns/docbook" version="5.0" xml:id="DVD-Booklet" xml:lang="en">
  <info>
    <title>Introducing Mandriva Linux</title>
      <revhistory role="calenco:workflow">
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>2008-03-11</date>
	  <authorinitials>Peter</authorinitials>
	  <revremark>write</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>Pingusa</authorinitials>
	  <revremark>check</revremark>
	</revision>
	<revision>
	  <revnumber>2008.1</revnumber>
	  <date>YYYY-MM-DD</date>
	  <authorinitials>To Be Attributed</authorinitials>
	  <revremark>proofread</revremark>
	</revision>
      </revhistory>
      
......

Wir haben hier als ein 3 Schritte Arbeitsfluss:

• Schreiben wurde von Peter am 11.03.2008 beendet
• technische Fehlerfreiheitsprüfung wird der Zeit von Pingusa durchgeführt
• Es ist noch kein Korrekturleser eingetragen

Um den Arbeitsfluss zu verändern, musst du nur den XML Code in der Datei bearbeiten und dem SVN übergeben:

• Ändere YYYY-MM-DD auf das aktuelle Datum, an dem die Arbeit beendet wurde
• schreibe deinen SVN Loginnamen in das <authorinitials> Feld, wenn du für diese spezielle Aufgabe verantwortlich sein willst
• ergänze oder entferne nach Belieben Aufgaben

Anweisungen für Übersetzer

1. Wann immer du ein neues Modul zu übersetzten beginnst oder eine bestehende Übersetzung bearbeiten willst, stelle sicher, dass das Original fertig gestellt wurde.
   • überprüfe dafür einfach den Workflow des Originals in der svnnav Oberfläche
   • Es muss am Ende zum Korrekturlesen (oder als "check") markiert sein
2. Beim Aktualisieren einer Übersetzung helfen dir zwei Werkzeuge:
   • der "Structure Diff Report" in der Überstzungsmodul-Seite sagt dir welche Elemente des Originals erneuert wurden, im Vergleich zur der Übersetzung. So kannst du einfach die XML Quelldateien vergleichen.
   • der "Diff Report" in der originalen Modulseite zeigt dir farbig die Unterschiede von vorherigen zur aktuellen Version