Wikipedia:Maldokumentasjon

Maler er en meget kraftig funksjonalitet i MediaWiki, men kan være forvirrende for nye brukere, og selv erfarne brukere kan ha vansker med å få noe fornuftig ut av de mer komplekse malene. Maler skal derfor ledsages av dokumentasjon for å forbedre brukervennligheten.

Maldokumentasjon skal forklare hva en mal gjør og hvordan man skal bruke den. Den skal være enkel nok til at en bruker uten fullstendig kunnskap om innviklethetene i malsyntaks - dette omfatter mange erfarne brukere som fokuserer oppmerksomheten på andre ting - kan bruke malen korrekt. Dette er spesielt viktig i tilfeller med maler som brukes svært mye.

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.
• 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 <code> 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).
• Kategorier og InterWikimedia-lenker, der det passer. På samme måte som dokumentasjonen må disse være inni en <noinclude> container. Mange malkategorier er tilgjengelige, se Kategori:Maler for å bla i dem.

Maldokumentasjon er ofte plassert på en underside av selve malen, og undersiden 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 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 <noinclude> 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 begrenset av ytelsesgrunner. Når dokumentasjonen plasseres på en underside unngår man dette. (MediaWiki utviklere har anbefalt dette av denne grunn).

Hvordan lage en dokumentasjonsunderside

Maldokumentasjonsundersider bør navngis og formateres ved bruk av det følgende generelle mønsteret.

Anta at malen din heter Mal:X. Den enkleste måten er å skrive følgende (husk "subst:") på slutten av malen:

{{subst:dokkode}}

Pass på at det ikke er mellomrom eller linjeskift mellom siste tegn i selve malen og {{.

Ved å bruke denne framgangsmåten vil du dessuten sette inn en automatisk kommenter (se Mal:Dokkode) som først blir synlig etter at du har lagret og deretter forsøker å redigere siden på nytt. Kommenteran veileder brukere som ikke er kjent med at kategorier legges inn på undersider. Den ser slik ut: <!-- Legg inn kategorier på /dok-undersiden, og interwikilenker på Wikidata, ikke her! -->

Lagre malen. Det skal da komme frem en boks med teksten "Maldokumentasjon" under selve malen. Til høyre står det en lenke som heter "opprett". Klikk på den og fyll inn passende dokumentasjon under overskriftene.

Se også

• {{Dokumentasjon}} – Transkluderer dokumentasjonen på malsiden og gir lenker for å vise, redigere og se historikken til dokumentasjonen
• {{Dokumentasjonsunderside}} – Forklarer at det som følger er dokumentasjon, og lenker til den dokumenterte siden