Wikipedija:Dokumentacija predloge

Predloge so uporabno orodje programja MediaWiki, a imajo lahko neizkušeni uporabniki težave z razumevanjem in uporabo te funkcije. Zato naj bi bile predloge opremljene z dokumentacijo, ki razlaga njihovo uporabo.

Na kratko naj bi dokumentacija predloge razložila, čemu je predloga namenjena in kako jo uporabiti. Idealno naj bi bila ta razlaga razumljiva tudi človeku, ki ni seznanjen z delovanjem Wiki sintakse. Posebej to velja za pogosto uporabljane predloge.

Dokumentacija naj bi vsebovala:

• namen - kaj predloga ustvari in zakaj jo je potrebno uporabljati, če ni to očitno
• parametre predloge - razlaga uporabe in njihove možne vrednosti
• zgled uporabe - izpisana koda kot jo je treba vključiti v članek ali na pogovorno stran, s parametri. Kodo je lažje kopirati, če je izpisana znotraj oznak <code> in </code> da izgleda takole. Pri bolj zapletenih predlogah je koristno vključiti nekaj kombinacij parametrov in poleg njih še predlogo samo. Za zgled glej dokumentacijo predloge Vandalizem.
• sorodne predloge - povezave do sorodnih predlog, še posebej če obstaja v nek namen cela serija predlog in/ali imajo zelo podobna imena.
• kategorije - za preglednost.

Ker se dokumentacija nanaša na predlogo samo in ne na vse strani kjer je predloga vključena, jo je treba dodati na stran predloge znotraj oznak <noinclude>...</noinclude>. Kot nakazuje ime, se tekst znotraj teh oznak ne vključi poleg kode predloge. Zaželjeno je, da se dokumentacija nahaja na podstrani predloge in se to podstran nato vključi na konec strani predloge. To olajša razlikovanje med kodo predloge, ki je lahko zelo dolga in zapletena, ter dokumentacijo. Omogoča tudi urejanje dokumentacije vsem, če je predloga iz kakšnega razloga zaščitena pred urejanjem. Nenazadnje pa zmanjša obremenitev sistema, ki mu ob vključevanju predloge ni potrebno procesirati še celotne dokumentacije.

Kako ustvariti dokumentacijsko podstran

Za preglednost naj bi bile vse dokumentacijske podstrani poimenovane po naslednjem vzorcu: vzemimo za primer, da imamo predlogo z imenom Predloga:Zgled. Podstran naj ima torej naslov Predloga:Zgled/dok.

Na ta naslov skopirajte naslednje

{{dokumentacijska podstran}}
<!-- Kategorije spadajo na dno te strani, medjezikovne povezave pa v Wikipodatke. -->

== Uporaba ==

== Glej tudi ==

<includeonly>
<!-- Kategorije spadajo sem, medjezikovne povezave pa v Wikipodatke -->

</includeonly>

Predloga na vrhu bo prikazala obvestilo, da gre za dokumentacijsko podstran, in povezavo do predloge ter uvrstila podstran v kategorijo Dokumentacijske podstrani.

Pod njo spada besedilo dokumentacije, med <includeonly>...</includeonly> pa ustrezne kategorije. Predloge naj bi bile v kategorijah razvrščene po imenu, zato dodajte razvrstilni ključ {{PAGENAME}}. Brez tega se predloga kategorizira pod črko P.

Shranite podstran in se vrnite na samo predlogo, v tem primeru Predloga:Zgled. Na koncu dodajte naslednje:

[--zadnja vrstica predloge--]<noinclude>{{Dokumentacija}}</noinclude>

To bo vključilo vsebino dokumentacijske podstrani na stran od predloge. Pomembno: prvi <noinclude> mora biti v isti vrstici kot konec predloge, sicer programje upošteva tudi prazne vrstice pri vključevanju predloge v članke, to pa v večini primerov ni zaželeno.

Lahko si tudi olajšate delo in začnete s tem korakom, ker se bo v tem primeru na strani predloge pokazal okvirček z rdečo povezavo do dokumentacijske podstrani.

Kategorije

• Umestitev predloge same v ustrezno kategorijo, dodaj kodo [[Kategorija:Ime kategorije]] znotraj sekcije <includeonly>...</includeonly> na podstrani dok.

• Ustvarjanje medjezikovne povezave za predlogo samo, poveži s predlogami z enako funkcionalnostjo v drugih jezikih z uporabo orodja »dodaj povezave«, vendar na strani same predloge, ne na dokumentacijski podstrani.

• Umestitev podstrani dok v kategorijo, dodaj kodo [[Kategorija:Ime kategorije]] znotraj sekcije <noinclude>...</noinclude> na podstrani dok.

• Umestitev članka, ki uporablja to predlogo, v ustrezno kategorijo, dodaj kodo [[Kategorija:Ime kategorije]] znotraj sekcije <includeonly>...</includeonly> v predlogi sami.