Hilfe:Vorlagendokumentation

Im Prinzip soll jede Vorlage mit einer Dokumentation ausgestattet werden.

• Bei trivialen, offenkundigen Fällen wie Navigationsleisten mit schlüssiger Namensgebung und ohne Parameter mag die sichtbare Dokumentation einmal entfallen; zumindest eine Kategorisierung muss aber noch geleistet werden.
• Bereits eine Infobox muss die Interpretation bestimmter Daten erläutern, könnte aber auf eine analoge Infobox zu einem übergeordneten Thema verweisen.
• Bei projektweit und häufig eingebundenen Vorlagen ist die Dokumentation unerlässlich.

In erster Linie informiert die Vorlagendokumentation die Anwender über die korrekte Benutzung, den Zweck und das zu erwartende Ergebnis. Darüber hinaus ergeben sich aus der Dokumentation auch Hinweise für die Programmierer; zu inneren Strukturen und Testfälle zur Überprüfung der richtigen Funktion. Nebenbei wird die Vorlage auf diesem Weg auch kategorisiert; möglicherweise gibt es vereinzelt auch noch Interlanguages.

Inhalte

Die Dokumentation muss die folgenden Punkte abdecken:

• Welchen Zweck hat die Vorlage?
  • Dazu reicht ggf. ein Satz oder ein Schlagwort.
  • Bei sehr gut selbsterklärenden Vorlagenbezeichnern, wie bei Navigationsleisten, kann eine Zweckbeschreibung ggf. entfallen.
• Welche Parameter gibt es? Ggf. auch „keine“.
  • Pflichtparameter und optionale Parameter sind zu unterscheiden; bei letzteren die Vorgaben zu beschreiben.
  • Formate, zulässige Werte und ungültige Angaben müssen erläutert werden, wenn hierüber Zweifel bestehen können.
• Kategorisierung

Außer in sehr einfachen Standardfällen (etwa Navigationsleiste) gehört dazu weiterhin:

• Kopiervorlage
  • Quellcode für eine Standard-Einbindung; mit Namen von Pflichtparametern oder häufig benötigten Optionen.
• Anwendungsbeispiele
  • Anwendungsbeispiele stellen den Quellcode für typische Fälle dar. Anschließend wird genau dieser Quellcode auch als Muster eingebunden.
  • Die ordnungsgemäße Funktion einer Vorlage nach Änderungen in der Programmierung lässt sich überprüfen, wenn zum Vergleich auch das zu erwartende Ergebnis genannt wird.
  • In manchen Fällen können Beispiele auch die Kopiervorlage ersetzen; namentlich wenn ohne Parameter sinnvoll nutzbar.

Einfache Dokumentation

Sie erfolgt direkt auf der Vorlagenseite.

Mittels <onlyinclude>..</onlyinclude> wird die eigentliche Programmierung umschlossen. Text oder Code außerhalb eines vorhandenen (!) derartigen Bereichs wird nicht eingebunden. Fehlt eine derartige Angabe, so muss nicht einzubindender Text mit <noinclude>..</noinclude> umschlossen werden, um nicht eingebunden zu werden. Außerhalb des einzubindenden Bereichs werden die Informationen zur Dokumentation geschrieben. Bewährt hat sich folgende Struktur:

<onlyinclude>Programmierung Programmierung Programmierung
Programmierung Programmierung Programmierung</onlyinclude>
Informationen zur Benutzung
Informationen zur Benutzung
[[Kategorie:Vorlage:Geeignete Kategorie]]

Gegenüber dem Einschluss der Dokumentation in <noinclude> hat das den Vorteil, dass genau ersichtlich ist, welche Leerzeichen oder gar Leerzeilen zur wirksamen Programmierung gehören. Insbesondere nach einem letzten </noinclude> können leicht auf die Darstellung wirksame aber auf der Programmierungsseite nicht erkennbare Leerzeichen und Leerzeilen verbleiben.

Dokumentation auf Unterseite

Dies erfolgt mittels der Vorlage:Dokumentation und ihrer Unterseiten.

Grundprinzip ist, dass nur die reine Programmierung auf der eigentlichen Vorlagenseite erfolgt und dort sonst nichts als die {{Dokumentation}} eingebunden wird. Alle weiteren Informationen werden auf die Unterseite /Doku oder ggf. weitere Unterseiten ausgelagert.

Das hat mehrere Vorteile:

• Die Programmierung kann geschützt werden.
  • Zumindest vor unangemeldeten Benutzern; bei stabiler Programmierung und sehr häufig eingebundenen Vorlagen auch so, dass sie nur von Administratoren bearbeitet oder bei Bedarf vorübergehend entsperrt werden.
  • Durch die seit einem Jahrzehnt möglichen Schutzstufe „Sichterrechte“ kann die historische Vorlage:Tausendfach verwendet weitgehend entfallen. Sichter begehen heutzutage nur selten unüberlegte Änderungen; falls doch waren sie auch durch bunte Kästen noch nie einzubremsen.
• In der Versionsgeschichte der Programmierung erscheinen nur noch Änderungen, die auch eine Auswirkung nach außen haben.
  • Verbesserungen innerhalb der Dokumentation stören hier nicht die Nachvollziehbarkeit der Versionsgeschichte; diese Änderungen haben nur örtliche Wirkung.
• Eine verbesserte Formulierung in der Beschreibung erzwingt nicht den Neuaufbau Abertausender Seiten, die die Programmierung einbinden.

Die optimale Struktur der Programmierungsseite ist:

<onlyinclude>wirksame Programmierung</onlyinclude>

{{Dokumentation}}

Seit 2008 hat die Auslagerung der Dokumentation hingegen keinen Einfluss mehr auf Vorlagenbeschränkungen, weil die Abschnitte in noinclude/onlyinclude nicht mehr mitberechnet werden.

Hinweis: Seit längerer Zeit werden bei der Bildung des Sortierschlüssels die Namensräume (hier also Vorlage:) ignoriert; es ist deshalb in der Regel für eine Vorlage:XYZ keine Angabe mehr erforderlich von expliziten Schlüsseln wie

• {{SORTIERUNG:XYZ}}
• [[Kategorie:Vorlage:kkkk|XYZ]]
• [[Kategorie:Vorlage:kkkk|{{PAGENAME}}]]

Insbesondere bei Infoboxen kann eine abweichende Sortierung in Infobox-Kategorien erwünscht sein, sonst würden alle Vorlagen unter „I“ für Infobox einsortiert; Navigationsleisten entsprechend.

Meta-Daten

Früher wurden im Zusammenhang mit einer Unterseite /Doku auch die Kategorien und Interlanguages auf einer gesonderten Unterseite /Meta ausgelagert. Damit wollte man in erster Linie die Aktivitäten der Internationalisierungs-Bots von der Beobachtungsliste fernhalten, und diese hatten möglicherweise nur begrenzte Schreibrechte.

Mit Einführung von Wikidata ist das obsolet, und es wurde im April 2018 eingestellt und wird nicht mehr unterstützt, führt vielmehr zu einer Fehlermeldung.

TemplateData

Mit dem Syntaxelement TemplateData lassen sich maschinell auswertbare Angaben vereinbaren, die zwischen der Dokumentation, automatisch generierten Anwendungshinweisen und Gültigkeitsprüfungen geteilt werden können.

Inzwischen ist das in der deutschsprachigen Wikipedia zum einzufordernden Standard geworden für alle gepflegten Vorlagen, die mit Parametern in enzyklopädische Artikel häufiger direkt eingebunden werden.

Auf der Dokumentationsseite wird eine Tabelle mit den Parametern generiert. Um Redundanz und Inkonsistenzen zu vermeiden, muss diese Tabelle im Kopfbereich als übersichtliche Zusammenstellung sichtbar sein. Die Zweckbeschreibung in TemplateData wirkt als Einleitungsabschnitt. In vielen Fällen kann die Vorlage damit bereits hinreichend dokumentiert sein.

Es kann sein, dass die Kurzbeschreibungen bei einer komplexeren Vorlage noch weiterer Erläuterungen bedürfen; in diesem Fall kann das im nachfolgenden Wikitext vertieft werden. Auch ein umfangreicherer Abschnitt zu Methodik und Hintergründen kann die spartanische Zweckbeschreibung ergänzen. Um TemplateData, zusätzliche Erläuterungen zu den Parametern sowie Beispiele und Kopiervorlage konsistent halten zu können, muss dies auch geschlossen im Wikitext einer einzigen Seite zusammengestellt sein: der Unterseite /Doku.

Vorlage:TemplateData/JSON erlaubt die Spezifikation der Informationen, ohne sich um die Syntax von JSON kümmern zu müssen.

Vorlagen, die nur in der Programmierung anderer Vorlagen verwendet werden sollen, können nicht sinnvoll mit den Formularwerkzeugen eingefügt werden, weil komplexe Programmierungspfade nicht mit dem sichtbaren Wikitext eines Artikels vergleichbar sind. Die Formularwerkzeuge weigern sich deshalb ggf.

• Gleichwohl mögen einzelne Vorlagen für Vorlagen mittels TemplateData dokumentiert werden, da dies der gewohnte Standard geworden ist, auch wenn das niemals in Werkzeugen wirksam werden kann.

Tests und Beispiele

Um die Anwendung von Vorlagen mit Parametern verstehen zu können, sollten immer einige Beispiele mit verschiedenen charakteristischen Werten und dem unterschiedlichen Resultat angegeben werden.

• Wenn die Vorlage nur ein Wort formatiert oder eine Verlinkung bildet, genügt ein Abschnitt auf der /Doku-Unterseite, so dass alles übersichtlich auf einer Seite dargestellt ist.
• Wenn die Vorlage umfangreichen Output produziert, wie das etwa bei Infoboxen der Fall ist, würde das die allgemeine Seite sprengen.
  • Hier sollte eine eigene Unterseite /Test angelegt und mit {{Dokumentation/Test}} gekennzeichnet werden.
  • Das gilt auch, wenn komplexe Parameterkonstellationen oder viele Fehlermeldungen zu behandeln sind.

Neben der Funktion als Beispielsammlung für Anwender sollen die Testfälle auch den Programmierern erlauben, nach Veränderungen an der Programmierung die odnungsgemäße Funktion zu überprüfen. Wenn das zu erwartende Ergebnis nicht trivial ist, so muss auch jedem Anwendungsfall eine Kurzbeschreibung des zu erwartenden Ergebnisses beigegeben werden.

Wartungsseite

Nur wenn recht umfangreiche Unterstützung zur Wartung und Pflege der Vorlage und ihrer Einbindungen gegeben wird, lohnt sich die Verwendung einer gesonderten Unterseite /Wartung. Damit soll der für Anwender der Vorlage interessante Teil über die richtige Einbindung übersichtlich gehalten werden.

Handelt es sich nur um ein, zwei Sätze zur Wartung, so ist es besser, einen kleinen Abschnitt innerhalb der Dokumentationsunterseite anzulegen.

Gliederung einer Dokumentationsseite

Einleitungsabschnitt

Der Zweck der Vorlage ist kurz zu umreißen.

Wenn mit TemplateData gearbeitet wird, kann die dortige Funktionsbeschreibung gleichzeitig als Einleitungsabschnitt genutzt werden und ist somit immer textidentisch und muss nicht doppelt gepflegt werden. Das Voranstellen von TemplateData weist außerdem Anwender des VisualEditor und des Vorlagenmeisters auf Unterstützung hin.

Die Funktionsbeschreibung oder zumindest deren Beginn, vielleicht die ersten fünfzig Zeichen werden in projektweiten Auflistungen als Suchtreffer angezeigt. Sie sollen deshalb bereits in den ersten Wörtern auf den Punkt kommen und die wesentlichen Schlagwörter liefern:

• Weblink zu example.org mit Spielergebnissen
• Infobox für einen Artikel über ein …
• Zitation aus Handbuch des Fähnlein Fieselschweif
• Formatierung einer Zahl

Ungeeignet sind hingegen langatmige Vorreden, die früher einmal üblich gewesen waren:

Diese Vorlage dient dazu, in projektweit einheitlicher Weise darzustellen, welche [Ende der Treffervorschau]

Parameter

Alle Parameter sind zu dokumentieren:

• Welche Bedeutung sie haben,
• ob Pflicht oder optional,
• Typ (Zahl, Datum, Wikitext, logischer Schalter = „boolesch“, kodierter Bezeichner),
• welche Formatierung (verlinkt oder unbedingt unverlinkt; Zahlen- und Datumsformate),
• welche Wirkung nicht angegebene Werte haben,
• bestimmte feste Ausdrücke,
• Beispielwerte.

Wenn mit TemplateData gearbeitet wird, liefert dies gleichzeitig die Tabelle aller Parameter. Damit wird auch eine Doppelarbeit vermieden, die ohnehin zu Inkonsistenzen neigen würde.

Kopiervorlage

Für Quelltext-Bearbeiter sollte immer zum Copy&Paste eine unausgefüllte Beispielsequenz angeboten werden.

Unbenannte Parameter können ggf. mit Platzhaltern besetzt werden. Als HTML-Kommentare <!-- ... --> können Hinweise mitgeliefert werden.

In manchen Fällen können Beispiele auch die Kopiervorlage ersetzen; namentlich wenn ohne Parameter sinnvoll nutzbar.

Beispiele

Beispiele für ausgefüllte Quelltexteinbindung und daraus generierte Darstellungen sind wichtig. Sie verdeutlichen genauer, welche Formatierungen für Parameterwerte erwartet werden, und bei Veränderungen an der Programmierung lässt sich sofort überprüfen, ob die Darstellung noch erwartungsgemäß erscheint.

Umfangreiche Beispiele sollten hingegen besser auf eine separate Test-Unterseite ausgelagert werden; wenn etwa die Darstellung oder Parameteranzahl sehr groß ist und dies in mehreren Varianten und mit Fehlersituationen durchgespielt wird.

Hinweise

Besondere Hinweise zur Verwendung, Entstehungsgeschichte, Programmierungsmethodik können die Beschreibung abrunden.

Hilfsmittel

Für einige Vorlagen gibt es besondere Software-Werkzeuge, die beim Ausfüllen, der Generierung von Werten oder bei der Wartung helfen. Sie können in einem gesonderten Abschnitt erläutert werden.

Siehe auch

Dieser Abschnitt richtet sich an diejenigen, die eine ähnliche Vorlage gesucht haben und noch nicht die ganz zielführende gefunden hatten.

Auf andere Vorlagen mit vergleichbarer Funktion und auf Projektseiten zur Thematik kann ggf. verwiesen werden.

Damit ist der für die Anwendung relevante Bereich abgeschlossen.

Wartung

Wenn nicht umfangreiche Wartungsaufgaben auf einer gesonderten Unterseite geschildert werden müssen, sollte auf Wartungskategorien oder entsprechende Linklisten hier verwiesen werden.

Dieser Abschnitt richtet sich an diejenigen, die die Einbindungen im Bestand pflegen und ggf. berichtigen.

Lua

Ganz am Ende der /Doku und unmittelbar vor den Kategorien kann die Vorlage:Dokumentation/Lua eingefügt werden. Sie ist für Anwender der aktuellen Vorlage normalerweise irrelevant, hilft aber, wenn jemand das Innere dieser Vorlage verstehen oder umprogrammieren möchte.

<includeonly>
{{Dokumentation/Lua|TemplatePar #check}}
[[Kategorie:Vorlage:kkkkkkkk]]
</includeonly>

Durch den Einschluss in <includeonly> wird vermieden, dass die Verlinkungen für die Dokumentationsseite wirksam werden; sie sollen nur die Programmierungen anzeigen.

Dieser Abschnitt richtet sich an diejenigen, die die Programmierung bearbeiten wollen.

Kategorisierung

Die Kategorisierung der Vorlage in Kategorie:Vorlage: wird in <includeonly> eingeschlossen; nicht die Dokumentationsseite, sondern nur die Programmierung soll kategorisiert werden.

Wahl des geeigneten Verfahrens

Immer über Unterseite soll dokumentiert werden, wenn eine der folgenden Situationen vorliegt:

• TemplateData vorhanden
• Vorlagenprogrammierung soll geschützt werden
• Umfangreichere Dokumentation
• Häufig benutzte Vorlage (in der Regel zusammen mit Halbschutz oder Dreiviertelschutz, also Änderung der Programmierung nur mit Sichterrechten)

Selbsteinbindung

Standardmäßig erscheint bei der Darstellung einer Vorlagenseite immer eine „Einbindung“ der Vorlage selbst. Das ist die natürliche Folge ihrer Programmierung.

• Das ist in vielen Fällen sinnvoll und gibt einen optischen Eindruck von der Wirkung der Vorlage.
• Es ist aber nur dann sinnvoll, wenn die Vorlage ohne Parameter auskommt und nicht bloß wirre Syntax zeigt:

  {{{1}}} {{{2}}}/ {{{3}}}

• Wenn nichts Brauchbares sichtbar wird, sollte die Selbstdarstellung unterbunden werden, indem die unmittelbare Programmierung umschlossen wird von includeonly.
• Im Abschnitt „Beispiele“ der Dokumentation sollten dann Musteranwendungen mit geeigneter Parameterversorgung gezeigt werden.

Wenn die Auswertung unsichtbar bliebe und für die Dokumentationsseite unerwünschte Folgen hätte, etwa eine Kategorisierung, kann auch durch geeignete Konstrukte (etwa nowiki mit #tag) der von der Vorlage generierte Quelltext dargestellt werden.

Zusätzliche Informationen

Abgesetzt und nach den Informationen für Anwender der Vorlage können weitere Aspekte dokumentiert werden.

Wartungsaufgaben

Hierunter fallen auch ausgelöste Wartungskategorien für den Fall von Anwendungsfehlern.

• Wenn es sich nur um wenige Zeilen handelt, bekommt dies schlicht einen Abschnitt auf der /Doku-Unterseite.
• Umfangreiche Darstellungen von Parameteranalysen sollten eine eigene Unterseite /Wartung erhalten und mit {{Dokumentation/Wartungsseite}} gekennzeichnet werden.

Die Auslagerung auf eine gesonderte Seite hat zur Folge, dass nur wenige Besucher der Vorlagenseite die Wartungsaufgaben zur Kenntnis nehmen, von den Wartungslinks erfahren und Probleme abarbeiten könnten.

Programmierung

• Auf Untervorlagen soll verlinkt werden, und ihr Verwendungszweck soll kurz umrissen werden.
• Weitere Unterseiten sind möglich, wenn eine ausgiebige Sammlung von Test- und Beispielfällen den Rahmen sprengen würde.
• Bei Verwendung von Lua sollen die Module und ggf. eine einzelne Funktion daraus verlinkt werden (siehe oben).

Serien

Größere Serien inhaltlich und programmtechnisch analoger Vorlagen sollten in einer Struktur realisiert werden, in der sich nach dem Vererbungsprinzip Programmierung und Dokumentation zentral teilen lassen. Das erlaubt dann auch eine gemeinsame Nutzung von TemplateData-Informationen, die nur noch von wenigen Parametern abhängen.

Beispiel: Die Vorlage:DEU, die selbst mit {{DEU}} in andere Seiten eingebunden wird, gehört zu einer Serie; die Dokumentation ist im Code der Vorlage mit {{Vorlagendokumentation Land mit Flagge}} eingebunden und kann unter Vorlage:Vorlagendokumentation Land mit Flagge bearbeitet werden. Jede Änderung an der Dokumentation betrifft aber alle Vorlagen der Serie und muss entsprechend formuliert werden.

Solche „Meta-Dokumentationen“ werden in der Kategorie:Vorlage:Metadokumentation gesammelt.

Kopiervorlagen

Zu einem einfachen Beispiel siehe oben.

Nachstehend eine Standardgliederung für eine Dokumentations-Unterseite mit TemplateData, in der keine vertiefenden Erläuterungen zum Verwendungszweck oder zu Parametern erforderlich sind:

<noinclude>{{Dokumentation/Dokuseite}}</noinclude>
{{TemplateData|JSON=
{ "description": "... Zweck ...",
  "params": { 
              .........
            },
  "format": "inline"
}             
|TOC=1}}

== Kopiervorlage ==
<pre>
{{Beispielvorlage|Pflichtparameter=}}
</pre>

== Beispiele ==
.........

<includeonly>
[[Kategorie:Vorlage:kkkkkkkk]]
</includeonly>