Entwicklung von Hilfetexten: Unterschied zwischen den Versionen

Aktuelle Version vom 2. Juni 2023, 09:38 Uhr

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:

Umgeben des eigentlichen Hilfetextes mit einem DIV Tag mit der ID 'txt'
Einfügen der Anweisung, die die Generierung des automatischen Inhaltsverzeichnisses unterdrückt.
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.

@@ Zeile 7: / Zeile 7: @@
 === 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:
+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.'''
@@ Zeile 17: / Zeile 17: @@
 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.
+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 [[Special:Categories|Kategorie]] pro Anwendung verwendet.
-=== Nutzung eines Templates für die Seiteninhalte ===
+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 [[BISWiki:Wiki Vorlagen|Templates bzw. Vorlagen]] gearbeitet.
+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 [[Spezial:Alle_Seiten|Templates bzw. Vorlagen]] gearbeitet. Siehe auch die [[mediawikiwiki:Help:Templates/de|Hilfe von Mediawiki dazu]].
-Es reicht dabei ein einziges Templates aus, das h-Template. Seine Nutzung wird in der [[Spielwiese]] demonstriert.
+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:
-=== Nutzung von Kategorien ===
+# Umgeben des eigentlichen Hilfetextes mit einem DIV Tag mit der ID 'txt'
-== Einbindung der Hilfetexte ==
+# Einfügen der Anweisung, die die Generierung des automatischen Inhaltsverzeichnisses unterdrückt.
+# 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 [[Pvedit000|wie in dieser Seite]] Teil eines Links ist.
+Verschiedene Lösungsmöglichkeiten werden in [https://stackoverflow.com/questions/20897400/passing-an-equal-sign-to-a-parameter-in-a-mediawiki-template dieser Stackoverflow Diskussion] genannt.
+In diesem Wiki existiert daher das Template <nowiki>{{=}}</nowiki>, welches ein '{{=}}' erzeugt. Die Alternative aus dem Stackoverflow Artikel, bei der die Templateparameter nummeriert werden (<code>1= ...</code>) 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
+:<nowiki>== Überschrift ==</nowiki>
-=== jQuery Werkzeugkasten ===
+;Fett und Kursiv
+:<nowiki>'''Fett''' und ''kursiv''</nowiki>
-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:
+;Aufzählungen mit und ohne Nummerierung
+:<nowiki># Nummerierte Aufzählung</nowiki>
+:<nowiki>* Nicht nummerierte Aufzählung</nowiki>
-* Abrufen von Seiten aus diesem Wiki samt Extraktion des eigentlichen Hilfetextes aus dem DIV Tag mit der ID 'txt'
+;Definitionslisten bzw. Einrückungen
-* Konvertierung von Links innerhalb des Textes mit Fallunterscheidung: Links zu externen Seiten - dazu zählen auch Interwikilinks in das [[BISWiki:Start|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.
+:<nowiki>;Ein Begriff</nowiki>
+:<nowiki>:Die eingerückte Erklärung des Begriffs</nowiki>
-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.
+=== Nutzung von Kategorien ===
-=== J2EE Nutzung ===
+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.
-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.
+Ein Beispiel für eine solche Kategorie ist [[:Category:Prüfungsverwaltung der Prüfungsämter|Prüfungsverwaltung der Prüfungsämter]].
-Zusätzlich sind hier ggf. HTML Vorlagen und CSS Code notwendig, um die Darstellung des Hilfetexts zu unterstützen.
+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.