=====iX-Wiki - Inhalte erstellen===== ====Redaktionelle Richtlinien==== Im Folgenden werden die für die Erstellung der unterschiedlichen Produkte notwenigen formalen sowie inhaltlichen Vorgaben spezifiziert. ===Handlungen anweisen=== * Enthält Standard Fehlerfälle, Ursache und Auflösung * Enthält Beispiele * Enthält Konzept und * (technische, fachliche) Voraussetzungen * Beschreibung der durchzuführenden Schritte in abgeschlossenen, zusammenhängenden Einheiten (z. B. Dokument erstellen, Dokument drucken, Dokument versenden) * Bedientipps und Hinweise sollen durch Icons gekennzeichnet werden, ebenso wie „Warnungen“ vor Bedienfehlern mit schwerwiegenden Folgen. ===Terminologie konsistent halten=== Die einheitliche Verwendung von Begriffen für dasselbe Element dient der Transparenz und dem Leseverständnis. | **Standard** | **Synonyme** | | Ansicht | View | | Dialog | Maske, Formular | | Register | Tab, Reiter, Registerkarte | | Schaltfläche/Aktion | Button, Schalter, Taste, Klick | | Option | Radiobutton (Einzeloption) (o) ◉ ( ) ◎ | | Kontrollfeld | Checkbox (auch für Multiselect-Optionen), ☑ [X] ❒ [ ] | | aktiv | ☑ [X] gewählt, ausgewählt, markiert, selektiert | | inaktiv | ❒ [ ] ◎ ( ) | | Schieberegler | Scrollbalken | | FIBU | Fibu, FiBu | ====Kapitel strukturieren==== * Commit-Prozess: wir veröffentlichen zu jedem Service Pack am Monatsende, was wir haben, auch wenn es noch unvollständig ist und Slavcho aktualisiert dann die Version einmalig, sobald wir fertig sind. * Dokumentation der letzten Jahresversion: nur gravierende Dokufehler, grobe Unstimmigkeiten, Kundenrückmeldungen und Patch-Erweiterungen werden hier dokumentiert bzw. angepasst. * Jeweils aktuelle Servive Pack Version: alle übrigen Erweiterungen plus aktuelle Baustellen plus Umsetzung von Minidokus. Wir legen eine modulare Struktur aller Themen und Informationen an, wobei pro Hauptordner oder je nach inhaltlichem Umfang enthaltene Unterordner aller enthaltenen Module alphabetisch angeordnet und somit leicht durchsuchbar sind. Das linke Menü des iX-Wiki soll nur noch Inhalte mit maximal zwei Ebenen Tiefe beinhalten; also Kapitel und Abschnitte; pro Kapitel wird ein neuer Namespace angelegt; Abbildung der Verzeichnisordner der iX-Haus Struktur plus modulweise strukturierte Unterkapitel; Beispiel: Buchhaltung -> Auflistung aller nachfolgenden Module als Kapitel: Dialogbuchhaltung, …, Sollstellung, …, Erlösschmälerung Parameter Liste, … Je nach Umfang entstehen so Kapitel mit einzelnen oder mehreren Modulbeschreibungen. Sind mehrere Modulbeschreibungen eines Unterordners der Menüstruktur so umfangreich, dass sie nicht sinnvoll gemeinsam in einem Kapitel nach einer gemeinsamen HowTo usw. Systematik bearbeitet werden können, ziehen wir dieses Kapitel hoch auf die Ebene des übergeordneten Kapitels, siehe zum Beispiel Hilfsprogramme aus der Fachadministration. Die rechte, im Text des Kapitels selbst enthaltene Menüstruktur liefert dann einen leicht durchsuchbaren Überblick zu den Abschnitten, bzw. Themen dieses Kapitels. Buchhaltungs-, Stammdatendruck, sowie übrige modulspezifische Druckmenüs werden jeweils wie ein eigenständiges Modul behandelt (Endknoten in Menüstruktur), d. h. wir fassen alle Drucklisten zu einem Druckkapitel pro Modul zusammen. Der Bereich „Was brauche ich dazu“ enthält alle Drucklisten als Einträge analog zu z. B. Registern anderer Kapitel. Abschnitt „Wie mache ich es“ enthält Details zum Druck etc., welche nicht allgemeiner Natur sind oder es wird auf die allgemeinen Bereiche verwiesen. Diese Strukturierung gibt eine erste Orientierungsmöglichkeit; sobald der Anwender ein Kapitel aufgerufen hat, sieht er eine Liste mit Einleitung, Überschriften aller Funktionen und Ansichten sowie den Administrationseintrag (Parameterbeschreibungen einzelner Register, Handlungsanweisungen, Workflowbeschreibungen), wobei die Textabschnitte eingeklappt sind, um auch bei umfangreichen Inhalten optimale Übersichtlichkeit zu gewährleisten; das rechtsseitige Inhaltsverzeichnis (TOC = Table of Content ) bildet hierbei wie oben beschrieben die interne Struktur pro Kapitel ab. Systematische Strukturierung: pro Kapitel ein Namespace mit vier Seiten plus zusätzlichen Seiten für abweichende Informationen: 1. Menüstruktur mit allgemeinen Bereichen; Seitenname „main“ > Titel der Seite „Was tue ich hier?“ 2. Besonderheiten der Bedienung für ausgewählte Prozesse und Schritt für Schritt Anleitungen mit Verweisen auf Beschreibungen allgemeiner Funktionen in eigenem Kapitel; Seitenname „howto“ > Titel der Seite „Wie tue ich es?“ 3. Beschreibung Benutzeroberfläche mit Tabellen, einzelnen Registern und Dialogen; Seitenname „parameter“ > Titel der Seite „Was brauche ich dazu?“ 4. Systemeinstellungen, Beschränkungen, Voraussetzungen, Lizensierung; Seitenname „system“ > Titel der Seite „Administration“ Die vier Seiten und ihre Spielarten sind in der Enddarstellung im übergeordneten Kapitel = Namespace versteckt, bzw. für den Anwender nicht einzeln aufrufbar (s. Admin => Konfiguration (Konfigurationsmanager), DokuWiki, Darstellung, hidepages: sidebar|system|main|howto|howto1|howto2|parameter|parameter1|parameter2). Sie dienen uns zu der Möglichkeit, verschiedene Inhalte zu übergreifenden Themen per include Befehl zusammenzustellen, z. B. alle Funktionsbeschreibungen oder alle administrativen Beschreibungen. Die Struktur der Unterseiten wird in der Seite start.txt organsiert und sieht pro Kapitel immer wie folgt aus: ====== Titel des Kapitels ====== ===== Was mache ich hier? ===== {{page>main&noheader&inline&nofooter}} ===== Wie mache ich es? ===== {{page>howto&noheader&inline&nofooter}} ===== Was brauche ich dazu? ===== {{page>parameter&noheader&inline&nofooter}} ===== Systemeinstellungen ===== {{page>system&noheader&inline&nofooter}} Der Befehl noheader sorgt dafür, dass die Unterseiten ohne deren 1. Überschrift eingebunden werden und damit die von uns gewünschte Struktur für die Inhaltsverzeichnisse der einzelnen Kapitel entsteht. Somit können die Unterseiten eine organisatorisch bedingte Überschrift behalten, welche beim Include nicht ausgegeben wird. Über die Inhaltsverzeichnisse, die abhängig von der Strukturierung links wie rechts am Seitenrand generiert werden, können sich Nutzer neben unserer geplanten Suchanleitung mittels Schlagwort-Umfeld-Suchen zusätzlich orientieren oder sie bei Bedarf, z. B. bei zu kleinem Bildschirm, einfach ausblenden. Die linke Navigation wird durch die Datei sidebar.txt gesteuert und bei reduzierter Fensterbreite automatisch in den Kopfbereich verschoben. Als Resultat sollen die Beschreibungen aller Module von iX-Haus und iX-Haus plus auf diese Weise vernetzt ineinandergreifen, über Querverweise Beziehungen untereinander herstellen und damit als Ausgangspunkt zur Selbsthilfe bei Anwendungsfragen dienen. Parameterbeschreibungen realisieren wir als einfache, zweispaltige Auflistungen, wobei in der linken Spalte die Feldbezeichnung etc. in Code-Formatierung und in der rechten Spalte der beschreibende Text enthalten ist. Achtung! Der beschreibende Text in Tabellen darf niemals als direkte Anrede formuliert sein, sondern sollte immer nur sachbezogen und im Passiv formuliert sein, z. B. „Schaltfläche xy dient dem Zurücksetzen des Passwortes. Die Schaltfläche muss dazu etwa drei Sekunden gedrückt werden.“ Die Bezeichnungen oberhalb von Abschnitten, Eingabefeldern oder Bereichen, welche optisch mehrere Eingabefelder und Schaltflächen etc. eines Dialogs oder Registers zusammenfassen, dienen uns fortan zur Strukturierung der Tabellen. Statt einer Zeile, in die diese Bezeichnung als Zwischenüberschrift eingetragen wird, setzen wir diese Bezeichnung als echte Überschrift, passend zur Ebene der gesamten Ansicht zum Beispiel als Überschrift 3 und legen darunter einen einzelnen Tabellenabschnitt an, der wiederum als Dropdown-Text formatiert und somit ausgeblendet werden kann. Gleichzeitig können wir so auch Querverweise aus beliebigen anderen Abschnitten und Kapiteln auf die Überschriften setzen, so dass aus anderen Parameterbeschreibungen ein Link zu genau dieser Stelle der Registerbeschreibung möglich ist. So kann zum Beispiel die Überschrift Adressdaten mit Parameterbeschreibungen für natürliche Personen aus anderen Parameterbeschreibungen des gleichen Moduls aufgerufen werden, wenn die konkreten Datenfelder äquivalent sind und der Querverweis damit Sinn macht. Beim erstmaligen Aufruf einer Seite ist so nur eine Liste der Bereiche eines Dialogs oder eines Registers sichtbar. Blendet der Benutzer alle Tabellenabschnitte beim Lesen nacheinander ein, erhält er eine vollständige Übersicht des Registers / Dialogs. Eine Schaltfläche rechts der Hauptseite ermöglich das komplette Ein- /Aus-Klappen aller folded-Elemente der Seite (folded-Plugin). Bei PDF-Erstellung werden alle folded-Elemente ausgeklappt wiedergegeben. ====Organisatorisches Konzept (neu: zur Übertragung von Minidokus!!)==== Minidokus sind einzelne, modul- oder themenspezifische Dokumente, die von Entwicklern und Produktmanagement zur Erstellung von Benutzerdokumentation verwendet werden, siehe Abschnitt Minidokumentation. Dabei handelt es sich um kurze Beschreibungen von Programmfunktionalitäten. Sie werden bei Neuentwicklungen angelegt und danach weiter gepflegt. Sobald Mini-Dokumentationen vollständig in die online Benutzerhilfe (zukünftig ins Wiki) eingeflossen sind, werden sie vom Redakteur archiviert (C:\Work\w_trunk\Intern\Technische Redaktion\Minidoku_integriert). Auf Info durch den Redakteur an den zuständigen Entwickler wird für die Datei im Patch bzw. ServicePack auch in der update.cmd entsprechend ein Löschbefehl eingebaut, damit beim Kunden keine veralteten Mini-Dokus mit aktueller Online-Doku konkurrieren. Zur formalen Struktur des Dokumentes siehe unten, Abschnitt „Interne Wordvorlagen“. ACHTUNG: der folgende Abschnitt ist inhaltlich veraltet!!!! Zum Release des iX-Wikis Sommer 2020 möchten wir einen möglichst vollständigen und möglichst aktuellen Stand der Benutzerdokumentation erreichen. Da die Übertragung der bestehenden Inhalte aktueller Kapitel in die neue Struktur einen zu hohen personellen Aufwand erfordert, legen wir der pünktlichen Bereitstellung der Inhalte folgendes Konzept zugrunde: Wir übertragen alle bestehenden iX-Haus Inhalte aus Google Sites (im Wiki Textformat) in die mit „main“ bezeichneten Textdateien der entsprechenden Kapitel der iX-Wiki Struktur. Fallen hierbei oder bei der Bearbeitung von Inhalten aus den Service Packs veraltete Textstellen auf, markieren wir diese in einer geeigneten Form und tragen den Bereich als ToDo in die gleichnamige Exceltabelle im internen Ordner der Technischen Redaktion auf Ebene des branch im work-Verzeichnis ein. Ansonsten bleibt die iX-Haus Dokumentation bis auf bestimmte Ausnahmen in der bisherigen Struktur bestehen. iX-Haus plus Inhalte werden wir nach Abwägung der Prioritäten modulweise in die neue Struktur überführen, bzw. fehlende Inhalte direkt in der neuen Struktur anlegen. Die Prioritäten legen wir dabei anhand der Anzahl Features fest, die sich während der Sprints für einzelne Module ergeben, z. B. erhält die höchste Priorität ein solches Modul, für das besonders viele Funktionen oder große Bereiche entwickelt oder überarbeitet wurden. Da die Arbeit an den Release Notes einhergeht mit der Arbeit an den iX-Wiki Inhalten, können wir bei der Erstellung der Release Notes entsprechende Einträge in der ToDo Liste anlegen und in der Folge parallel abarbeiten. =====Formate für iX-Wiki===== ====Code- und Sonderzeichendarstellung==== ++++| Für Code oder Sonderzeichen bietet das Wiki-System unterschiedliche Varianten an. Hintergrund ist entweder, einen ganzen Block im Wiki exemplarisch hervorzuheben, einzelne Wörter oder Zeichen, die ansonsten vom Wiki als Steuercode interpretiert werden. Die einfachste Lösung ist, eine Zeile mit zwei Leerzeichen beginnen zu lassen. So können mehrzeilige Blöcke, notfalls auch mit Scrollbalken für besonders langen Text geniert werden. In Codeblöcken gibt es in der Regel keine weiteren Auszeichnungen des Textes wie **fett** //kursiv// __unterstrichen__ oder Ähnliches. Einzelne Wörter oder Textabschnitte werden mit ''doppelten Apostrophzeichen'' geklammert wie Code dargestellt. \\ Achtung1: Auch eingeklammerte Leerzeichen sind dann Bestandteil des Codeformats... ''F2 ''-Taste oder ''F2''-Taste?\\ Achtung2: Das versehentliche Weglassen eines Apostrophs hat Einfluss auf das Layout des nachfolgenden Wikitextes. Einzelne Wörter oder Textabschnitte werden mit ''doppelten Apostrophzeichen'' geklammert wie Code dargestellt. Achtung: auch eingeklammererte Leerzeichen sind dann Bestandteil des Codeformats... ''F2 ''-Taste oder ''F2''-Taste? Achtung1: Auch eingeklammerte Leerzeichen sind dann Bestandteil des Codeformats... ''F2 ''-Taste oder ''F2''-Taste?\\ Achtung2: Das versehentliche Weglassen eines Apostrophs hat Einfluss auf das Layout des nachfolgenden Wikitextes. Mit dem code-Tag können ebenfalls ganze Abschnitte als Code tituliert werden, wodurch Wiki-Interpretationen entfallen. So können auch Zeichen wiedergegeben werden, die sonst als Wikiformatierungszeichen ''geschluckt'' werden. Auch wenn ein code-Tag inline geschrieben ist, sorgt er dafür, dass der code-Abschnitt als separater Absatz dargestellt wird! Daher gibt es auch noch einen nowiki-Tag für das Aussetzen von Wiki-Innterpretationen. So können auch Zeichen wiedergegeben werden, die sonst als Wikiformatierungszeichen ''geschluckt'' werden. Wenn ein nowiki-Tag inline geschrieben ist, bleibt der nowiki-Abschnitt inline! Für das nowiki-tag gibt es eine auch verkürzte Schreibweise mit doppelten Prozentzeichen. Ich empfehle, das nowiki-tag auszuschreiben, da es in der späteren Bearbeitung transparenter ist: man sieht wo der Block startet und wo er endet. Ein doppeltes %-Zeichen kann Anfang oder Ende eines unformatierten Blockes sein, somit versehentlich größere Abschnitte 'entformatieren'. Zum Verständnis, was als Sonderzeichen betrachtet wird, ist eine Liste der Codes sinnvoll, die einer Interpretation im Wiki unterliegen. Es gibt bestimmte Zeichenfolgen, die zu Bildern oder Sonderzeichen gewandelt werden. Hier eine Sammlung aus der Dokuwikisyntax: === Text to Image Conversions === ++++| Im öffentlichen Teil sind die Grafikersetzungen wie Smileys nicht eingeplant. Für die interne Organisation werden aber z. B. das Fixme sowie die Ausrufezeichen und Fragezeichen als Symboldarstellung genutzt. DokuWiki converts commonly used [[wp>emoticon]]s to their graphical equivalents. Those [[doku>Smileys]] and other images can be configured and extended. Here is an overview of Smileys included in DokuWiki: * 8-) %% 8-) %% * 8-O %% 8-O %% * :-( %% :-( %% * :-) %% :-) %% * =) %% =) %% * :-/ %% :-/ %% * :-\ %% :-\ %% * :-? %% :-? %% * :-D %% :-D %% * :-P %% :-P %% * :-O %% :-O %% * :-X %% :-X %% * :-| %% :-| %% * ;-) %% ;-) %% * ^_^ %% ^_^ %% * m( %% m( %% * :?: %% :?: %% * :!: %% :!: %% * LOL %% LOL %% * FIXME %% FIXME %% * DELETEME %% DELETEME %% ++++ === Text to HTML Conversions === ++++| Hier sind für iX-Wiki die Pfeile, Copyright und ggf. die spitzen Klammern (für Variablendarstellung) interessant. Typography: DokuWiki can convert simple text characters to their typographically correct entities. Here is an example of recognized characters. -> <- <-> => <= <=> >> << -- --- 640x480 (c) (tm) (r) "He thought 'It's a man's world'..." -> <- <-> => <= <=> >> << -- --- 640x480 (c) (tm) (r) "He thought 'It's a man's world'..." The same can be done to produce any kind of HTML, it just needs to be added to the [[doku>entities|pattern file]]. There are three exceptions which do not come from that pattern file: multiplication entity (640x480), 'single' and "double quotes". They can be turned off through a [[doku>config:typography|config option]]. ++++ === Quoting === ++++| Der Einsatz von Quoting-Darstellung in iX-Wiki ist nicht vorgesehen. Aber man stößt u. U. auf den Effekt, sollte man Zeilen mit schießenden spitzen Klammern beginnen... Some times you want to mark some text to show it's a reply or comment. You can use the following syntax: I think we should do it > No we shouldn't >> Well, I say we should > Really? >> Yes! >>> Then lets do it! I think we should do it > No we shouldn't >> Well, I say we should > Really? >> Yes! >>> Then lets do it! ++++ ++++ ====Einklappung per Folded-PlugIn==== ++++|Die Einklappungen können für ganze Textblöcke (Steuerung über vier Pluszeichen) oder innerhalb von Zeilen erfolgen (Steuerung über zwei Pluszeichen). Eine Verschachtelung von Blöcken ist in Kombination mit einer WRAP-Klammer möglich. Rechts außen ist Navigationsbalken ''Alles aus/einklappen'' als Schalter verfügbar. Per Default sind alle Abschnitte einer Seite eingeklappt, wenn diese geladen wird. === Verschachtelte Einklappungen === With the help of the [[https://www.dokuwiki.org/plugin:wrap|WRAP-Plugin]] you can create nested folds: ++++ Outer Fold | The trick is to wrap the inner fold: ++++ Inner Fold | This is the content of the inner fold. In addition an inline fold can be used too++| and this is an inline fold++. ++++ The inline fold is realized in the text line++| and this is an inline fold++. It will be expanded too. ++++ ++++ Outer Fold | The trick is to wrap the inner fold: ++++ Inner Fold | This is the content of the inner fold. In addition an inline fold can be used too++| and this is an inline fold++. ++++ The inline fold is realized in the text line++| and this is an inline fold++. It will be expanded too. ++++ ++++ ==== Überschriften ==== ++++| Engl. ''header'', Einklappung mit sectiontoggle technisch nicht ausgeschlossen, derzeit werden nur Inhalte darunter mit folded eingeklappt... Tastaturkommandos für die Bildung von Überschriften mit Shift + Alt + …: * 0 übergeordnete Überschrift * 1 H1 oberste Überschrift mit tag aus sechs Gleicheitszeichen * 2 H2 tag aus fünf Gleicheitszeichen * 3 H3 tag aus vier Gleicheitszeichen * 4 H4 tag aus drei Gleicheitszeichen * 5 H5 unterste mit tag aus zwei Gleichheitszeichen * 8 Überschrift in gleicher Ebene * 9 Überschrift untergeordnet Im Editmodus kann im Browser mit Mausklick auf Icons (H-Symbole) eine neue Überschrift eingefügt werden (mit oder ohne Ebenenwechsel oder Ebebenauswahl) (Code) * HH in gleicher Ebene wie die aktuelle (8) * H>H untere Überschrift (9) * H ''Raten-/Stundungsvereinbarung'' > ''Ratenvereinbarung'' \\ Positioniert wird der Pfad direkt unterhalb der Hautüberschrift mit einer Zeile Abstand bzw. bei Funktionen im Fließtext. ===Tabellen=== Abschnitte in Tabellen, welche die Bereiche eines Dialogs kennzeichnen, werden mit Überschriften der niedrigsten Ebene formatiert. Beispiel: Bereich Info im Dialog Meldung ===Dialog Meldung=== == Info == ^ Feld ^ Beschreibung ^ | ''Betreff'' | Benennung des Betreffs der Meldung, z. B. "Wasserrohrbruch" \\ manueller Umbruch in Tabellenzelle ansonsten -Tag nutzen! | Manueller Umbruch (auch in Tabellen): doppelter Backslash gefolgt von Leerzeichen ''\\ '' Umbruch mit Absatz (in Tabellen nur innerhalb einer WRAP-Klammer): mit doppeltem Enter.\\ Bitte unnötig geklammerte manuelle Umbrüche vermeiden: "Wasserrohrbruch\\ " -> "Wasserrohrbruch" \\ (Dies funktioniert zwar oftmals beides, Variante 1 ist jedoch anfällig für Folgefehler und beim Bearbeiten schlechter zu lesen.) Auszeichnung von Schaltern oder Modulnamen durch inline Code (Klammer durch doppelte ‘‘Apostrophen‘‘). | Die Kombination aus zwei Leerzeichen zu Absatzbeginn und Markierung kompletter Zeile mit einer Code-Klammer erzeugt einen Block-Code (-> Absatzformat, breiterer Coderahmen, dies ist i. d. R. nicht erwünscht). Nummerierte Handlungsschritte mit -, Einrückung von Unterkategorien ist möglich mit zwei weiteren Leerzeichen - erster - 1a - 1b - zweiter - dritter Unsortierte Listen mit *, Einrückung ist möglich mit zwei weiteren Leerzeichen * * * * Aufzählung * Subaufzählung * Subaufzählung * Aufzählung * Aufzählung ===Internes=== Dokumentation von Stellen mit Klärungsbedarf über nodisp-Tag mit Parameter 2: FIXME **Was noch zu tun ist** :?: oder FIXME **Fragestellung** :?: => soll nur im Editormodus gezeigt werden. FIXME **ToDo ...** :!: oder FIXME **Frage ...** :?: wäre auch ohne Anmeldung sichtbar! In Tabellen muss zur korrekten Ausführung von nodisp die Anweisung innerhalb eines -Tags stehen! Größere Baustellen können mit einer Zu-Erledigen-Box abgehandelt werden. ++++