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 Doku-Projekts wird von der technischen Redaktion eine neue Seite im Redaktionsbereich vorbereitet und die beteiligten Autor erhalten hierzu einen Link von DSN oder ARR.

Im diesem Abschnitt beschreiben wir den Ablauf der Erstellung von Inhalten für das iX-Wiki (Wiki) in Zusammenarbeit mit Entwicklung und Produktmanagement. Der Fokus liegt hierbei auf Beschreibungen für komplexe 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 Dokumentationsprozess umzustellen, so dass Minidokus direkt im Wiki erstellt, bearbeitet und abschließend zur Veröffentlichung freigegeben werden. Kleinere Funktionen und Erweiterungen werden wie bisher durch die Redaktion auf Basis der Updatetexte nach Abschluss eines Sprints in das Wiki eingearbeitet.

Die Redaktion legt für einen neuen Wiki-Inhalt auf Basis einer Mustervorlage eine neue Seite im internen Redaktionsbereich an. Diese wird als Projektseite an die beteiligten Autoren kommuniziert und enthält die grundlegenden Strukturen, welche vom jeweiligen Bearbeiter ergänzt und erweitert werden können. Entwickler oder Produktmanager können sich so in der Anfangsphase der Umsetzung auf die inhaltlichen Aspekte des Projekts konzentrieren und formlos auf der Projektseite editieren und kommentieren. Die Projektseite wird parallel zur und nach Abschluss der Entwicklung durch die technische Redaktion bearbeitet. Vor der Freigabe einer Seite bzw. Übernahme einer Projektseite in die aktuelle Kundenversion des Wiki erfolgt eine Endkontrolle durch alle Beteiligten.

1. Die Redaktion legt für ein neues Thema eine neue Seite im Redaktionsbereich an.
2. Der Link zu dieser Seite wird an alle Beteiligten versendet.
3. Der Entwickler erstellt Inhalte in Stichpunkten 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>Dieser Punkt wird in Sprint xy nochmals überarbeitet.</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.