Wikipedia:Sjabloondocumentatie

Overzicht
beheerpagina's

Sjablonen zijn een krachtig hulpmiddel van de MediaWiki-software, maar zijn voor nieuwe en zelfs voor ervaren gebruikers soms moeilijk te begrijpen. Om bij een sjabloon door de wikicode te moeten lopen om uit te vinden hoe het precies werkt zou daarnaast een tijdrovende klus zijn. Daarom is het zaak sjablonen goed te documenteren om zo de bruikbaarheid en toegankelijkheid te verbeteren. De documentatie moet duidelijk uitleggen wat het sjabloon doet en hoe het werkt. Een gebruiker zonder al te veel kennis van de syntaxis van sjablonen zou aan de hand van de documentatie het sjabloon correct moeten kunnen gebruiken.

Inhoud van de documentatie

Sjabloondocumentatie zou tenminste één, maar liever meerdere van de volgende punten moeten bevatten:

• Doel - Het doel van het sjabloon. Wat kun je ermee? Welke voordelen biedt het?
• Gebruik - In welke situaties wordt het sjabloon gebruikt? Als er vergelijkbare sjablonen zijn, geef dan aan welke je wanneer het best kunt gebruiken en wat de voor- en nadelen zijn. Dit verkleint de kans op foutief gebruik. Onder dit kopje wordt vaak ook een leeg parameteroverzicht getoond dat gebruikers eenvoudig kunnen kopiëren en plakken in het artikel om het aldaar in te vullen.
• Voorbeeld(en) - Een typisch voorbeeld van gebruik van het sjabloon in wikicode, alsook het resultaat dat die code geeft. Als het nodig is voor de uitleg van parameters kunnen meerdere voorbeelden worden gegeven.
• Parameters - De beschikbare parameters met een korte uitleg. Geef ook aan of ze verplicht zijn of optioneel. Als er beperkingen aan zitten (bijvoorbeeld als de waarde alleen een getal mag zijn of alleen 'ja' of 'nee'), geef dat dan ook aan.
• TemplateData - TemplateData. Voor een goede werking van de visuele tekstverwerker.
• Afhankelijkheden - Als het sjabloon gebruik maakt van andere sjablonen, een module, TemplateStyles of Wikidata, benoem die dan. Dit is vooral handig voor gebruikers die aan het sjabloon werken. Enkele sjablonen voor de weergave hiervan zijn te vinden in de Categorie:Wikipedia:Sjablonen sjabloondocumentatie.
• Gebruikte afbeeldingen - Voor gebruikte afbeeldingen die níét linken naar de bestandspagina (zoals gebruikelijk het geval) kan met Sjabloon:Ontlinkte afbeelding alsnog ernaartoe gelinkt worden, om aan mogelijke licentievoorwaarden te voldoen. Ook is het handig voor de vindbaarheid voor hergebruik.
• Zie ook - Een lijstje met relevante links en verwante sjablonen.

Hoe aan te maken

Standaard

Voor de weergave van de documentatie wordt sjabloon {{Documentatie}} gebruikt. Plaats dit sjabloon onderaan het te documenteren sjabloon, tussen <noinclude>-tags. Dit laatste zorgt ervoor dat de documentatie niet wordt getoond op pagina's waar het sjabloon gebruikt wordt, maar alleen zichtbaar is op de sjabloonpagina zelf. De documentatie plaats je in de eerste parameter van Documentatie. Dat ziet er dan als volgt uit:

<!-- Laatste regel sjablooncode. --><noinclude>
{{Documentatie|1=
Doel van dit sjabloon is...

== Gebruik ==
...
}}

[[Categorie:Wikipedia:Sjablonen ...]]
</noinclude>

Het sjabloon Documentatie zorgt ervoor dat de documentatie in een duidelijk van het sjabloon te onderscheiden box komt te staan. Plaats de openende <noinclude>-tag vlak achter de sjablooninhoud en niet op een nieuwe regel. De nieuwe regel zou anders terechtkomen op pagina's waar het sjabloon gebruikt wordt en dat is meestal onwenselijk. Plaats de categorieën van het sjabloon buiten het Documentatie-sjabloon, maar bínnen de <noinclude>-tags.

Als subpagina

Bovenstaande methode is de aanbevolen manier. Het heeft als voordeel dat er geen aparte pagina aangemaakt hoeft te worden en de documentatie en het sjabloon overzichtelijk bij elkaar te vinden zijn. In sommige gevallen is het echter wenselijk of noodzakelijk de documentatie op een aparte pagina te plaatsen. Voorbeelden van zulke situaties zijn:

• Het sjabloon is beveiligd, maar de documentatie moet bewerkbaar blijven.
• Er wordt een tabel in de documentatie gebruikt. Op de sjabloonpagina kan dat in principe ook, maar omdat die daar in een parameter wordt meegegeven, moet elk verticaal streepje ( | ) vervangen worden door | of het magic word {{!}}. Zeker bij grotere tabellen kan dat onhandig zijn.

In dergelijk gevallen kan voor de documentatie een subpagina van het sjabloon worden aangemaakt met de naam /doc. Bovenaan de subpagina wordt het sjabloon {{Doc subpagina}} geplaatst, om aan te geven dat het om een documentatiepagina gaat. Plaats vervolgens onderaan de sjabloonpagina het Documentatie-sjabloon, maar nu zonder parameters. De documentatie op de subpagina verschijnt vanzelf in de box op de sjabloonpagina.

Let op: De categorieën van het sjabloon horen altijd op de sjabloonpagina, niet op de /doc-pagina.

Gedeelde documentatie

Voor groepen van sjablonen met eenzelfde functionaliteit is het aan te raden één documentatiepagina aan te maken en deze te delen met de verschillende sjablonen. Gebruik hiervoor de parameter |pagina= van sjabloon Documentatie en vul deze op elk van de te documenteren sjablonen in met de naam van de gedeelde pagina:

{{Documentatie|pagina=Sjabloon:Naam van gedeelde docpagina}}

In de box wordt de inhoud van de opgegeven pagina getoond.

Plaats de gedeelde documentatiepagina in Categorie:Wikipedia:Sjablonen gedeelde documentatie.

Zie ook

• {{Documentatie}} - Plaatst de documentatie in een onderscheidende box.
• {{Doc subpagina}} - Te plaatsen op /doc-subpagina's. Geeft aan dat de inhoud van die pagina documentatie is en linkt naar het gedocumenteerde sjabloon.
• Categorie:Wikipedia:Sjablonen sjabloondocumentatie - Sjablonen die gebruikt kunnen worden voor de documentatie.
• (en) Uitleg <noinclude>-tags.