Die aktuellen DIN-Normen zur „Erstellung von Nutzungsinformationen (Gebrauchsanleitungen) für Produkte“ (September 2021) sind in der Originalausgabe im Redaktionsbüro hinterlegt und können bei DSN ausgeliehen werden.

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 in einem Worddokument. Sie werden bei Neuentwicklungen angelegt und danach weiter gepflegt. Ziel ist es, alle Minidokus bis auf wenige Ausnahmen wie spezielle Kundenschnittstellen oder Sonderprogrammierungen als Wiki-Inhalte anzulegen. Sobald diese Mini-Dokumentationen vollständig ins Wiki eingeflossen sind, werden sie vom Redakteur archiviert (C:\Work\w_trunk\Intern\Technische Redaktion\Minidoku_integriert) und mit einem Zeitstempel am Ende des Dokumentes mit dem Verweis auf den entsprechenden Wiki-Inhalt versehen. Für die betreffende Datei wird im Patch bzw. Service Pack in der update.cmd automatisiert ein Löschbefehl eingebaut, damit beim Kunden keine veralteten Mini-Dokus im Doku-Verzeichnis des Programms auftauchen.

Wir veröffentlichen zu jedem Sprint am Monatsende eine interne Version der Release Notes mit den Zwischenständen zur Umsetzung der Tasks. Dabei sind die Neuerungen monatlich gekennzeichnet. Zum Quartalsende bzw. zum Release eines Service Packs integrieren wir alle neuen Inhalte in die aktuelle Branchversion des Wiki. Slavcho aktualisiert nach Abschluss die jeweilige Kundenversion des Wiki.

In der Jahresversion des Wiki (z. B. 20.23.0) werden ab der Freigabe einer neuen Kundenversion (z. B. zu Service Pack 20.23.1) nur gravierende Unstimmigkeiten, Kundenrückmeldungen und ggf. Patch-Erweiterungen dokumentiert bzw. angepasst, in der aktuellen Service Pack-Version alle übrigen Erweiterungen plus aktuelle Baustellen plus Umsetzung von Minidokus aus dem Altbestand.

Fehlerbehebungen und Anpassungen in den Ebenen Trunk minus 4 bis Trunk unterhalb der Branchebene werden wöchentlich in den Patch Notes kommuniziert.

Im Folgenden werden die für die Erstellung von Inhalten notwendigen formalen wie inhaltlichen Vorgaben spezifiziert.

• 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 sind durch Icons gekennzeichnet, ebenso wie „Warnungen“ vor Bedienfehlern mit schwerwiegenden Folgen.
• Standard-Fehlerfälle, Ursachen und Auflösung
• Beispiele

Die einheitliche Verwendung von Begriffen für dasselbe Element dient der Transparenz und dem Leseverständnis.

Wir streben eine modulare Struktur aller Themen und Informationen an, wobei pro Ordner bzw. Unterordner in der Menüstruktur des Programms eine Wiki-Seite angelegt wird. Diese sind alphabetisch angeordnet und somit leicht durchsuchbar.

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.

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.