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.


Developed by StudentB