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 Beziehnung zwischen Hilfetextschnipsle 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). Dahinter einfach die nächste freie Nummer angefügt, welches dies ist kann über die entsprechende Kategorie ermittelt werden.

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 der J2EE Programmierung 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.

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. Diese 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

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 ist es mit der heutigen Version des Wikis nicht möglich die Kategorien über das Templates 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.

Einbindung der Hilfetexte

jQuery Werkzeugkasten

Für die Einbindung der Textbausteine wird eine Sammlung von jQuery Scripts zur Verfügung gestellt. Diese müssen in der Lage sein diese Aufgaben zu erfüllen:

• Abrufen von Seiten aus diesem Wiki samt Extraktion des eigentlichen Hilfetextes aus dem DIV Tag mit der ID 'txt'
• Konvertierung von Links innerhalb des Textes mit Fallunterscheidung: Links zu externen Seiten - dazu zählen auch Interwikilinks in das BIS Wiki - müssen zum Öffnen der Seite in einem neuen Fenster führen. Links innerhalb dieses Wikis zu anderen Hilfeseiten sollen hingegen im gleichen Kontext geöffnet werden, so dass eine Verlinkungen von Themen innerhalb der Hilfeschnipsel möglich ist. Die Unterscheidung erfolgt darüber, ob die Links eine komplette URL (http....) enthalten oder nur eine relative.

Diese Werkzeuge sind für alle Anwendungen identisch. Damit sie auch in den Entwicklungssystemen nutzbar sind werden sie auf dem BIS Webserver abgelegt und müssen dort gepflegt werden.

Einbindung in die Nutzersicht

In der J2EE Programmierung werden in den Anwendungen Bausteine in Form von Tag Files implementiert, denen als Parameter nur der Seitenname übergeben werden muss und welche die jQuery Scripts verwenden um den Hilfetext zu holen.

Zusätzlich sind hier ggf. HTML Vorlagen und CSS Code notwendig, um die Darstellung des Hilfetexts zu unterstützen.