Entwicklung von Hilfetexten

Die Aufgabe dieses Wikis ist es den BIS Anwendungen Textschnipsel zur Verfügung zu stellen, die per Javascript Einbindung direkt in den Oberflächen angezeigt werden können. Gleichzeitig sind die Wiki Seiten die Rückfalloption für NutzerInnen, die kein Javascript in ihren Webbrowsern nutzen können oder wollen.

Aufbau der Hilfeseiten im Wiki

Ziel dieses Wikis ist es Hilfetexte abzubilden, die an verschiedenen Stellen in den BIS Anwendungen benötigt werden. Es geht dabei um stark kontextabhängige Texte, also Texte die sich auf ganz konkrete Fragen, Funktionen bzw. Anwendungsseiten beziehen.

Eine Wiki Seite pro Hilfetext

Auch wenn die Hilfetexte ohne Javascript zugänglich sein müssen ist es das Hauptziel dieses Hilfesystems den NutzerInnen direkt in ihrem Kontext die entsprechenden Texte anzeige zu können. Die technischen Details dazu werden weiter unten beschrieben, eine grundsätzliche Entscheidung besteht aber darin, dass eine 1-zu-1 Beziehung zwischen Hilfetextschnipsel und Wiki Seite besteht. Oder anders gesagt:

Jeder Hilfetext wird in eine separate Wiki Seite gepackt.

Der Name einer Seite stellt dabei den eindeutigen Schlüssel für einen Hilfetext dar. Es ist nicht möglich mehrere Hilfetextschnipsel innerhalb einer Wiki Seite unterzubringen.

Ermittlung eines Titels für eine neue Seite

Da der Seitentitel wie zuvor beschrieben der Schlüssel ist, der einen bestimmten Hilfetext für die nutzenden Anwendung identifiziert, ist das Format der verwendeten Namen ein wichtiges Thema. Die Seitennamen haben nur technische Zwecke und sollen insbesondere in HTML und Javascript Einbindungen keine Probleme verursachen können. Sie haben keinerlei Informationscharakter für die NutzerInnen und werden daher in diesem Wiki nicht angezeigt.

Die Seitennamen sollen nur aus den Buchstaben a-z und den Ziffern 0-9 bestehen und es soll ein pro Anwendung einheitliches Präfix verwendet werden (z. B. 'pvedit' für die Prüfungsverwaltung für die Prüfungsämter). Zusätzlich wird eine eigene Kategorie pro Anwendung verwendet.

Einmal verwendete Titel dürfen nicht mehr geändert werden um Probleme bei der Einbindung durch die dann entstehende Umleitung zu vermeiden. Eine Umbenennung kann nur vorgenommen werden, wenn alle alten Referenzen ebenfalls geändert werden, sowohl in den nutzenden Anwendungen (J2EE Programmierung, SharePoint) wie auch hier im Wiki.

Nutzung eines Templates für die Seiteninhalte (h-Template)

Die Hilfetextschnipsel müssen einheitlich im HTML Code makiert sein, auch soll die Nutzung von Kategorien homogen erfolgen und zusätzliche Information zum Verwendungszweck strukturiert abgebildert werden. Es wird daher mit Templates bzw. Vorlagen gearbeitet. Siehe auch die Hilfe von Mediawiki dazu.

Es reicht dabei ein einziges Templates aus, das h-Template. Seine Nutzung wird in der Spielwiese demonstriert. Im Normalfall wird eine Seite in diesem Wiki nur aus einer einzigen Anwendung des h-Templates bestehen. Dieses Template hat mehrere Aufgaben:

1. Umgeben des eigentlichen Hilfetextes mit einem DIV Tag mit der ID 'txt'
2. Einfügen der Anweisung, die die Generierung des automatischen Inhaltsverzeichnisses unterdrückt.
3. Einfügen der als Templateparameter übergebenen Kurzbeschreibung des Hilfetextes, die für Formatierungen hier im Wiki ebenfalls mit einem speziellen DIV Tag umgeben wird. Als Kurzbeschreibung kann ggf. der Titel der Seite in der Anwendung genutzt werden, sofern dieser entsprechende Aussagekraft hat.

Die Verwendung von Templates führt manchmal zu irritierenden Effekten beim Anklicken der bei Zwischenüberschriften anzeigten 'Bearbeiten' Links: Diese Links führen in die Bearbeitung des Templates und nicht der eigentlichen Seite. Es muss statt dessen immer der 'Seite bearbeiten' Link am Seitenanfang verwendet werden.

Problematische Zeichen wie '=' in Templateinhalten

Das Gleichheitszeichen kann nicht ohne weiteres innerhalb eines Templates verwendet werden, selbst wenn es wie in dieser Seite Teil eines Links ist.

Verschiedene Lösungsmöglichkeiten werden in dieser Stackoverflow Diskussion genannt.

In diesem Wiki existiert daher das Template {{=}}, welches ein '=' erzeugt. Die Alternative aus dem Stackoverflow Artikel, bei der die Templateparameter nummeriert werden (1= ...) wird z. B. in Pvedit000 angewendet.

Formatierungen für Hilfetexte

Die Hilfetexte sollen eher sparsam mit den Formatierungsmöglichkeiten umgehen. Dies hat seinen Grund darin, dass die aufnehmenden Anwendungen die entsprechenden Formatierungsoptionen anbieten bzw. berücksichtigen müssen. In den meisten Fällen sollte es ausreichen wenn eine Beschränkung auf diese Formatierungen erfolgt:

H2 Überschriften

== Überschrift ==

Fett und Kursiv

'''Fett''' und ''kursiv''

Aufzählungen mit und ohne Nummerierung

# Nummerierte Aufzählung

* Nicht nummerierte Aufzählung

Definitionslisten bzw. Einrückungen

;Ein Begriff

:Die eingerückte Erklärung des Begriffs

Nutzung von Kategorien

Hilfeseiten einer Anwendung sollen durch eine gemeinsame Kategorie gekennzeichnet werden. Die Kategorien spielen - wie zuvor beschrieben - eine wichtige Funktion bei der Ermittlung von Seitennamen und sollen es uns auch ermöglichen die langfristige Pflege besser bewältigen zu können.

Ein Beispiel für eine solche Kategorie ist Prüfungsverwaltung der Prüfungsämter.

Leider war es mit der früher verwendeten Version des Wikis nicht möglich die Kategorien über das Template zu setzen. Die Kategorie muss daher in jeder Seite explizit gesetzt werden. Ein Beispiel findet sich in der zuvor verlinkten Kategorie für die Prüfungsverwaltung. In den Kategorienseiten finden sich Vorlagen mit den entsprechenden Formatierungen, die bei neuen Seiten einfach kopiert werden können.

Die Kategorien werden im linken Menü verknüpft, damit auf diese Weise ein direkter Zugang zu den einzelnen Themenbereichen gelingt. Es ist sinnvoll in den Kategorienseiten gerade bei größeren Anwendungen mit vielen Seiten zentrale Texte direkt zu verknüpfen, damit von dort aus weitergegangen werden kann.