iX-Wiki-Inhalte erstellen für Co-Autoren

Wesentliche Infos für Co-Autoren zur Erstellung einer iX-Wiki-Seite findet ihr hier auf einen Blick (ausführliche Infos im Abschnitt Technische Infos für iX-Wiki-Autoren).

Wenn Du das hier liest, hast Du wahrscheinlich schon alle Werkzeuge und Berechtigungen…

• Werkzeuge: Browser, z. B. Firefox.
• Berechtigungen: Das Schreiben in iX-Wiki ist nur nach Anmeldung möglich. Wir verwenden jeweils unseren Kürzel-Code (Kleinbuchstaben) in Kombination mit einem Passwort. Die Benutzeraccounts in iX-Wiki werden administrativ gepflegt. Infos hierzu und Einrichtung neuer User in iX-Wiki laufen per E-Mail über DSN und ARR.
  Der Autor benötigt außerdem Netzwerkzugriff und Schreibrechte für das Verzeichnis \\srv-dev\Dokuwiki und dessen Unterverzeichnisse. Diese werden durch SMV oder die Crem IT vergeben.
• Standort: Zu Beginn eines Projekts wird hierfür von der technischen Redaktion eine neue Seite im Playground vorbereitet und der Autor bekommt einen Link hierzu von DSN oder ARR. Diese kümmern sich im Vorfeld um die entsprechende Mustervorlage (universelle Mustervorlage).

Im diesem Abschnitt beschreiben wir den Ablauf der Erstellung von Inhalten fürs Wiki in Zusammenarbeit mit Entwicklung und Produktmanagement. Es geht demnach um Beschreibungen für größere Funktionen oder neue Module, zu denen bislang von den einzelnen Entwicklern Worddokumente erstellt werden, so genannte Minidokus. Das Ziel des Entwicklungsteams ist es, nach und nach den bisherigen Prozess umzustellen, so dass jede neue Dokumentation direkt vom entsprechenden Entwickler im Wiki erstellt, dort von der Redaktion bearbeitet und abschließend zur Veröffentlichung freigegeben wird. Kleinere Funktionen und Erweiterungen werden durch die Redaktion - wie bisher - nach Abschluss eines Sprints (insbesondere zum Quartalsende vor Freigabe einer neuen Kundenwiki-Version) auf Basis der Release Notes an den entsprechenden Stellen in der betreffenden Wiki-Version ergänzt und eingearbeitet.

Wir haben eine separate Muster-Seite im Namespace Playground aufgebaut. Die Redaktion bildet für ein neues iX-Wiki-Projekt aus dem Muster eine neue Seite im Playground. Diese wird an die beteiligten Autoren kommuniziert. Diese Projektseite enthält die grundlegenden Strukturen, welche initial vom jeweiligen Bearbeiter ergänzt und bei Bedarf erweitert werden können. Letztere werden nach weitestgehender/abschließender redaktionellen Bearbeitung dann in die jeweilige Branchversion verschoben. Die verwendeten Links werden hierbei berücksichtigt. Developer oder Produktmanager können sich daher in der Anfangsphase auf die inhaltlichen Aspekte des Projekts konzentrieren und ohne Manschetten im Playground editieren und auch kommentieren. Eine Endkontrolle sollte nach der Verschiebung erfolgen. Hier sind dann nur noch kleinere Korrekturen zu erwarten.

1. Die Redaktion legt für ein neuen Thema eine neue Seite im Playground an. Dabei wird eine Mustervorlage verwendet, welche die klassische Struktur der Wiki-Inhalte vorgibt:
   http://srv-dev/xampp/DokuWiki/Version.20.21.2/doku.php?id=playground:muster
2. Der Link zu dieser Seite wird an alle Beteiligten versendet.
3. Der betreffende Entwickler erstellt Inhalte als Stichpunkte und fügt im zugehörigen Sybille-Ticket Screenshots zur konkreten Umsetzung an.
4. Der PM prüft, ob fachlich alles stimmt und ergänzt die Einleitung unter „Was mache ich hier?“.
5. Der Redakteur redigiert und layoutet die Inhalte und fügt das fertige Kapitel im Wiki-Branch ein.
6. Entwickler und PM weisen bei zukünftigen Entwicklungsschritten nach Veröffentlichung auf die Notwendigkeit von Anpassungen hin.

Der Bearbeitungsmodus wird über die Schaltfläche Bearbeiten rechts unterhalb des anzupassenden Abschnitts gestartet.

Der Bearbeitungsmodus wird über die Schaltfläche Diese Seite bearbeiten (rechts oben im Seitenmenü) gestartet.

Die meisten Bedienelemente sind selbsterklärend oder weisen einen erläuternden Tool-Tip auf.

• Die Symbolleiste oberhalb des Textbereichs für Formatierungen, Überschriften, Links, Aufzählungen, …. Schaltflächen mit kleinem Dreieck rechts unten öffnen ein Auswahlmenü, das mit erneutem Klick auch wieder geschlossen werden kann. Fast alle lassen sich auch durch Tastaturkommandos bedienen.
• Rechts außen sind allgemeine Schaltflächen zu finden. Interessant ist hier der kontextsensitive Schalter Seite bearbeiten / Seite anzeigen.
• Links unten sind die Schaltflächen für Speichern, Vorschau und Abbrechen zu finden. Die Vorschau erfolgt über die Schaltfläche Vorschau. Sie wird unterhalb des Editorbereichs aufgebaut, also ggf. nach unten Scrollen.
• Rechts unten können der automatische Zeilenumbruch ein/ausgeschaltet sowie mit den Pfeilen oder dem 'Griff' die Größe des Editorbereichs geändert werden.

Die 'Projektautoren' benötigen relativ wenige Formatierungen. Die meisten hiervon sind auch über die vorgenannte Symbolleiste abrufbar. Die meisten Formatierungen erfolgen 'klammernd', d. h. Formatanweisungen stehen im Quelltext also meist vor und nach dem formatierten Abschnitt! Aufzählungen verwenden am Zeilenbeginn doppeltes Leerzeichen mit Listenzeichen - (für nummerierte Liste) oder * für Listenpunkt. In Listen sind auch Einrückungen möglich.

• Einfacher Zeilenumbruch im Quellcode: Für einen Absatz braucht es eine Leerzeile (also 2-mal Enter) oder für einen Zeilenwechsel die Formatanweisung doppelter Backslash gefolgt von einem Leerzeichen \\ .
• code: Für Feld-, Modulnamen oder für Parameterangaben verwenden wir zwei Aposotrophzeichen ''codetext''. Eine ganze Codezeile kann mit doppelten Leerzeichen am Zeilenanfang generiert werden. Manchmal will man aber auch einen Text generieren, welche dann vom Parser (ungewollt) als Codeanweisung interpretiert wird. Hier helfen Ausnahmedefinitionen, die wir unter Code und Sonderdarstellung detailliert beschreiben.
• Überschriften: mit mehreren Gleichheits-Zeichen in separater Zeile stehend. Je mehr desto höher die Hierarchie (max. 6, min 2).
• Pfeile: => ⇒ und -> → (Gleichheitszeichen oder Bindestrich gefolgt von spitzer Klammer geschlossen bzw. Größer-Zeichen). Weitere Sonderzeichen siehe Sonderzeichenauswahl aus der Symbolleiste (über die Schaltfläche mit dem Omega-Zeichen).
• Tabellen: Spalten von Tabellen werden mit Pipezeichen | generiert, die Überschriftszeile ggf. mit ^-Zeichen. In Tabellen bitte keinen Zeilenumbruch durch Return und/oder Leerzeile einsetzen! Hier funktionieren Zeilenwechsel mit Hilfe der Doppelbackslash-Leerzeichen-Kombination. Komplexere Tabellenzellengestaltung ist mit <WRAP>...<WRAP> möglich. Hier gerne Rückfrage an einen techn. Redakteur, wenn das Thema Tabellengestaltung akut ist.
• Querverweise: Interne Hyperlinks werden i. d. R. erst vom Lektorat generiert. Sie verweisen nur auf interne Seiten, die im Hyperlinkdialog auswählbar sind. Eine Ergänzung der SeitenId mit #-Zeichen im Code des Links verweist dann ggf. noch auf eine Abschnittsüberschrift innerhalb dieser Seite. Fußnoten ¹⁾ sind prinzipiell auch interne Hyperlinks.
• Hinweise und Warnungen: können innerhalb einer Zeile mit wrap-Tags mit den Parametern tip oder important generiert werden: <wrap tip>...</wrap> … oder …. Solche Hinweise können auch als separate Absätze gebildet werden. Hier ist dann ein WRAP-Tag (mit Großbuchstaben) einzusetzen: <WRAP tip >...</WRAP>

Mit dem „nodisp“-Kommando können Textabschnitte zu diversen Zwecken wie Vorläufigkeit nach Veröffentlichung oder als interner Kommentar für den Leser ausgeblendet werden.

Beispiel:

<nodisp 2>Interner Kommentar oder vorläufige Inhalte nach Veröffentlichung</nodisp>

Beispiele für Layoutprobleme nach Bearbeitung/Ergänzung von Inhalten:

• Schließendes Formattag vergessen oder verstümmelt (bei mehrstelligen Codes ein fehlendes Zeichen oder in schließender Tagklammer Slash vergessen)
• Fehlende zweite Leerzeile oder ein fehlendes Leerzeichen nach doppeltem Backslash ⇒ Unerwartetes Verhalten im Zeilenumbruch
• Fehlendes/Überzähliges Pipe-Zeichen oder manueller Zeilenumbruch in einer Tabellendefinition ⇒ unvollständige Tabellenanzeige
• Fehlendes Leerzeichen nach einem schließenden Formattag ⇒ zusammengeschobene Wörter.

Noch Fragen? Die beantwortet dir gern die technische Redaktion.