Redigerer W:no:Wikipedia:Maldokumentasjon (avsnitt)

== Hva skal inkluderes ==
Maldokumentasjon skal dekke:

* '''Hensikten''' med malen: hva den gjør - og i tilfelle det ikke er åpenlyst - hvorfor det må gjøres. Hvis det finnes andre maler med lignende navn eller hensikter, er det en god ide å nevne dem, for å redusere sjansen for at feil mal blir brukt.
* '''[[Hjelp:Maler#Parametere|Parameterne]]''' i malen: hvorvidt de er nummerert, navngitt eller valgfrie, og i tilfelle de er valgfrie, hva standardverdiene er og hvilken effekt de har. Hvis en parameter kan ta bare et begrenset sett verdier eller er begrenset på en eller annen måte, for eksempel at den bare kan bruke "ja", "nei" eller et tall, skal dette forklares tydelig.
* '''Brukseksempler''': spesifiser den eksakte wikteksten som skal brukes og resultatet den produserer. Wikiteksten kan være omsluttet av en &#x3C;code&#x3E; container, for å gjøre det tydelig. Hvis malen for eksempel kan brukes på ulike måter, med eller uten valgfrie parametere, gi da en rekke eksempler. En god måte å gjøre dette på er å transkludere selve malen inn i dokumentasjonen noen få ganger (det vil si bruk av live eksempler), med forskjellige parametere hver gang og liste opp parameterne som brukes i hvert tilfelle.
* '''Relaterte maler''': hvis malen er med i en familie av maler, ta med lenker til disse - og pass spesielt på at hver mal i familien er lenket fra hver av de andre, da dette forenkler navigasjonen. (En separat navigasjonsmal kan være nyttig for dette formålet, se [[Mal:Beskyttelsesmaler]]).
* '''[[wikipedia:Kategorisering|Kategorier]]''' og '''[[wikipedia:InterWikimedia-lenker|InterWikimedia-lenker]]''', der det passer. På samme måte som dokumentasjonen må disse være inni en &#x3C;noinclude&#x3E; container. Mange malkategorier er tilgjengelige, se [[:Kategori:Maler]] for å bla i dem.

Maldokumentasjon er ofte plassert på en [[wikipedia:underside|underside]] av selve malen, og undersiden [[wikipedia:Transklusjon|transkluderes]] på slutten av malsiden. Dette atskiller malkoden - som ofte er kompleks - fra dokumentasjonen, og gjør dokumentasjonen lettere å redigere. Dette tillater også at maler kan [[wikipedia:Retningslinjer for beskyttelse|beskyttes]] når det trengs, mens alle kan redigere dokumentasjonen. Denne metoden kalles noen ganger "template doc page pattern".

Dokumentasjon for en hvilken som helst slags mal skal alltid være omsluttet av en &#x3C;noinclude&#x3E; container, så den ikke vises når malen brukes på en annen side. Tekst på selve malsiden inngår i mengden tekst som må prosesseres når malen vises, og dette er [[wikipedia:Malgrenser|begrenset]] av ytelsesgrunner. Når dokumentasjonen plasseres på en underside unngår man dette. (MediaWiki utviklere har <span class="plainlinks">[http://en.wikipedia.org/w/index.php?title=Wikipedia:Village_pump_(technical)&diff=prev&oldid=69888944 anbefalt]</span> dette av denne grunn).