Seitenleiste
playground:ixwiki_konzept
Inhalt
iX-Wiki - Inhalte erstellen
- 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?
Wie mache ich es?
Was brauche ich dazu?
Hallo. Ich bin ein kleiner Blindtext. Und zwar schon so lange ich denken kann. Es war nicht leicht zu verstehen, was es bedeutet, ein blinder Text zu sein: Man ergibt keinen Sinn. Wirklich keinen Sinn. Man wird zusammenhangslos eingeschoben und rumgedreht – und oftmals gar nicht erst gelesen. Aber bin ich allein deshalb ein schlechterer Text als andere? Na gut, ich werde nie in den Bestsellerlisten stehen. Aber andere Texte schaffen das auch nicht. Und darum stört es mich nicht besonders blind zu sein. Und sollten Sie diese Zeilen noch immer lesen, so habe ich als kleiner Blindtext etwas geschafft, wovon all die richtigen und wichtigen Texte meist nur träumen.
Abschnitt 2 von Parameter1
Das ist ein Abschnitt zum include-Thema, Details finden Sie im externen Link https://www.dokuwiki.org/plugin:include
Abschnitt 3 von Parameter1
Die Syntax von include wird hier beschrieben: https://www.dokuwiki.org/plugin:include#syntax
Abschnitt 4 von Parameter1
Bavaria ipsum dolor sit amet wea ko, dea ko obandeln muass.
Abschnitt 5 von Parameter1
Und nochmal weils so schön ist: Zu fast jedem Plugin gibts eine Doku… der Admin gibt notfalls die benötigte Info.
Die Syntax von include wird hier beschrieben: https://www.dokuwiki.org/plugin:include#syntax
Abschnitt 6 von Parameter1
Abschnitt 6 ist hier leer…
Systemeinstellungen
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.
playground/ixwiki_konzept.txt · Zuletzt geändert: 2023/03/13 14:09 (Externe Bearbeitung)
Seiten-Werkzeuge
