Hilfe:Vorlagendokumentation

aus Wikipedia, der freien Enzyklopädie
Wechseln zu: Navigation, Suche

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.[1]
  • 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[Bearbeiten | Quelltext bearbeiten]

Die Dokumentation muss die folgenden Punkte abdecken:

  • Welchen Zweck hat die Vorlage?
    • Dazu reicht ggf. ein Satz oder ein Schlagwort.
  • 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.

Einfache Dokumentation[Bearbeiten | Quelltext bearbeiten]

Sie erfolgt direkt auf der Vorlagenseite.

Mittels der Anweisung <onlyinclude> werden nach der eigentlichen Programmierung die Informationen zur Dokumentation geschrieben; jedoch wird durch diese Anweisungen verhindert, dass sie in die Zielseite eingebunden werden. 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[Bearbeiten | Quelltext bearbeiten]

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.
  • 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.[2]

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[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

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.

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.

Tests und Beispiele[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

Einleitungsabschnitt[Bearbeiten | Quelltext bearbeiten]

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.

Parameter[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

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.

Beispiele[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

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

Wartung[Bearbeiten | Quelltext bearbeiten]

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

Hilfsmittel[Bearbeiten | Quelltext bearbeiten]

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.

Lua[Bearbeiten | Quelltext bearbeiten]

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

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

Siehe auch[Bearbeiten | Quelltext bearbeiten]

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

Wahl des geeigneten Verfahrens[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

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

Wartungsaufgaben[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

  • 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[Bearbeiten | Quelltext bearbeiten]

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[Bearbeiten | Quelltext bearbeiten]

Zu einem einfachen Beispiel siehe oben.

Nachstehend eine Standardgliederung für eine Dokumentations-Unterseite mit TemplateData, in der keine näheren 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>

Anmerkungen[Bearbeiten | Quelltext bearbeiten]

  1. In sehr seltenen Fällen katgorisieren Vorlagen sich auch gleich selbst.
  2. en:Wikipedia:Template limits #History