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

Sie erfolgt direkt auf der Vorlagenseite.

Mittels der Anweisungen noinclude/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:

<poem class="mw-code"> <onlyinclude>Programmierung Programmierung Programmierung Programmierung Programmierung Programmierung</onlyinclude> Informationen zur Benutzung Informationen zur Benutzung [[Kategorie:Vorlage:Geeignete Kategorie]] </poem>

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 Vorlage:Vorlage 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 Administatoren 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.

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

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.

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. 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 Einleitungsabschnitt kann der spartanischen Zweckbeschreibung vorangehen. 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.

Lua

Ganz am Ende der /Doku und unmittelbar vor den Kategorien kann die Vorlage:Lua-Vorlage eingefügt werden. Sie leitet auf Informationen, die für den Anwender der aktuellen Vorlage weitgehend irrelevant sind, und ist erforderlich, wenn jemand das Innere dieser Vorlage verstehen oder umprogrammmieren möchte.

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

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

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.

Weitere Informationen

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

Wartung

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

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 näheren Erläuterungen zum Verwendungszweck oder zu Parametern erforderlich sind:

<noinclude>{{Dokumentation/Dokuseite}}</noinclude>
 <templatedata>
 { "description": "... Zweck ...",
   "params": { 
               .........
             }
 }             
 </templatedata>

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

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

  <includeonly>
  [[Kategorie:KkKkKkKkKk]
  </includeonly>
 </noinclude>