Hilfe:Vorlagen/ Erklären

Vorlagen: Finden – Verwenden – Benennen – Erstellen – Erklären

Nur selten ist eine Vorlage intuitiv verständlich; deshalb gehört üblicherweise eine Beschreibung dazu. Das Vorgehen dazu wird hier erläutert. Auch bucheigene Vorlagen sollten in der Regel eine Dokumentation erhalten, damit künftige Mitautoren des Buches informiert sind; es kommt auch vor, dass eine solche Vorlage für andere Bücher und damit für andere Autoren nützlich ist.

Einfache Vorlage ohne Erklärung

Wenn in Ausnahmefällen auf eine Beschreibung verzichtet werden kann, gehört an das Ende der Vorlage folgender Vermerk:

<noinclude>''Wenn zu dieser Vorlage etwas zu erläutern ist, dann ersetze in der Vorlage 
den Abschnitt innerhalb von <noinclude> durch {{Dokumentation}} und erstelle die Unterseiten.''

[[Kategorie:Vorlage für Buchgestaltung]]</noinclude>

Als Kategorie ist natürlich diejenige einzutragen, die zur Art der Vorlage passt – siehe Vorlagen finden.

Vor allem in einfachen Vorlagen aus der Anfangszeit von Wikibooks wurde sehr oft auf eine Beschreibung verzichtet, auch wenn sie angemessen wäre.

Vorlage zur Dokumentation

Im Normalfall gehört an das Ende der Vorlage folgender Vermerk:

<noinclude>{{Dokumentation}}</noinclude>

Mithilfe der Vorlage:Dokumentation wird eine Doku-Unterseite vorbereitet und angezeigt. Diese Unterseite /Doku enthält die eigentliche Beschreibung der Vorlage. Am besten ist es, das folgende Gerüst zu kopieren und auszufüllen

== Zweck ==
== Parameter ==
=== Der Parameter 1 ===
=== Der Parameter "inhalt" ===
=== Weitere Parameter ===
== Beispiele ==
== Weitere Hinweise ==

In den folgenden Abschnitten gibt es Hinweise zu den möglichen Inhalten. Als Beispiel wird Vorlage:Kasten benutzt.

Am Ende der Seite wird vor allem die Kategorie der Vorlage eingetragen, also eine der folgenden Varianten:

<includeonly>[[Kategorie:Vorlage für Buchgestaltung|{{PAGENAME}}]]</includeonly>
<includeonly>[[Kategorie:Regaleigene Vorlage|{{PAGENAME}}]]</includeonly>
<includeonly>[[Kategorie:Bucheigene Vorlage|{{PAGENAME}}]]</includeonly>

Für projektweite und bucheigene Vorlagen ist dabei die passende Kategorie anzugeben. Nur in Ausnahmefällen (bei bestimmten Aufgaben) wird mehr als eine Kategorie eingetragen. (In der Vergangenheit gehörten die Kategorien in eine Unterseite /Meta. Das wird aber als unpraktisch empfunden und für neue Vorlagen nicht mehr benutzt.)

Zusätzlich sind über die Schaltfläche Vorlagendaten verwalten die gleichen Informationen in einem Standardformat einzutragen, damit die MediaWiki-Software die Benutzung von Vorlagen künftig automatisieren und erleichtern kann. Die Beschreibung dazu ist unten im Abschnitt Vorlagen-Spezifikation zu finden.

Zweck, Verwendung

Dieser Abschnitt muss die eigentliche Funktion der Vorlage beschreiben. Außerdem gehört hierher eine Kopiervorlage in einem Abschnitt <pre>{{Vorlage|Text ...}}</pre>, die eine Autorin auf die Buchseite kopiert und bei den Parametern mit den konkreten Werten ausfüllt:

{{Kasten
 |style=Info
 |inhalt=
}}

Sinnvoll ist es, alle wichtigen Parameter aufzuführen. Es ist keine allgemeine Empfehlung sinnvoll, inwieweit Standardwerte eingetragen werden oder ob die Parameter in einer Zeile hintereinander oder in mehreren Zeilen stehen sollten.

Parameter

Der Hauptteil der Dokumentation besteht in der Erläuterung aller Parameter. Zu jedem Parameter werden folgende Angaben benötigt:

Name oder Nummer
Muss der Parameter benutzt werden, oder ist er optional?
Zweck des Parameters, ggf. Arbeitsweise oder Steuerung der Vorlage
mögliche Werte, Standardwert (falls nichts angegeben wird)

Üblich ist es, jeden der wichtigsten Parameter in einem eigenen Abschnitt zu erläutern. Das sind oft (aber nicht immer) die obligatorischen Parameter. Weitere Parameter können in einem eigenen Abschnitt zusammengefasst werden. Wichtig bei dieser Gliederung sind die Lesbarkeit und die Übersichtlichkeit der Beschreibung; die Autorin, die eine Vorlage verwenden will, soll die Bedeutung der Parameter schnell finden und erkennen können.

Beispiele

Je nachdem, wie die Vorlage verwendet wird und was die Parameter ermöglichen, können Beispiele sinnvoll sein – siehe Vorlage:Infoleiste.

Weitere Hinweise

In diesen Abschnitt gehören bei Bedarf folgende Angaben:

Begründung, warum die Vorlage sinnvoll oder notwendig ist
Erklärung für einzelne Teile der Definition, falls spezielle Kenntnisse benötigt werden (auch spätere Nutzer sollen die Vorlage verstehen können)
Hinweise, wie die Vorlage ggf. erweitert werden kann
Angaben, was bei Änderungen an der Vorlage zu beachten ist
Links zu weiteren Erläuterungen
Fußnoten mit <references />

Vorlagen-Spezifikation

Mit Hilfe der Parsererweiterung <templatedata> können die Parameter einer Vorlage in dem maschinenlesbaren Format JSON spezifiziert werden. Diese Spezifikation wird unter anderem vom VisualEditor verwendet.

Ausführliche Erläuterungen zu dieser Parsererweiterung findet man auf folgenden Seiten:

Help:TemplateData – Hilfe-Seite
Extension:TemplateData – genaue Beschreibung aller Parameter

Vergleichbare Vorlage in anderen WMF-Projekten

Wenn es auch in anderen Projekten der Wikimedia Foundation – Wikibooks in anderen Sprachen, Wikipedia usw. – eine vergleichbare Vorlage gibt, kann die Vorlage am zentralen Speicherort Wikidata eingetragen werden. Dazu gibt es im Menü links bei den „Werkzeugen“ den Link Wikidata-Datenobjekt.