Vikipedija:Šablonų dokumentavimas

 Plume pen w.png  Čia pateiktas pasiūlymas oficialioms Vikipedijos taisyklėms ar tvarkai.
Prašome pasisakyti aptarimo puslapyje.

Šablonai MediaWiki programinėje įrangoje yra labai naudingi, tačiau naujokams (net ir patyrusiems vartotojams) gali būti sunku juos suprasti ir taisyklingai naudoti. Dėl šios priežasties šablonų puslapiuose turi būti dokumentacijos.

Šablono dokumentacija paaiškina, ką šablonas daro ir kaip juo naudotis. Visiškai nepatyrusiam naudotojui, nepažįstančiam suktos šablonų sintaksės, turėtų būti nepaprastai lengva suprasti šabloną ir taisyklingai jį naudoti. Tai ypač svarbu tuose šablonuose, kurie naudojami daugelyje straipsnių.

Kaip dokumentuoti šablonus?Keisti

Po šablonu reikia įterpti dokumentavimo šabloną:

{{Dokumentavimas}}

Kaip įterpti dokumentacijasKeisti

Dokumentacijosm įterpti yra vienas būdas, kuris nesugadina šablono.

Norėdami įterpti dokumentaciją, atsidarykite šablono redagavimo puslapį (paspausdami mygtuką „Redaguoti“ puslapio viršuje). Tuomet nueikite į pačia šablono pabaigą ir taip, kaip parodyta pavyzdyje žemiau, įterpkite dokumentacijos šabloną {{Dokumentavimas}}:

[--paskutinė šablono eilutė--]<noinclude>

{{Dokumentavimas}}

[--paskutinė dokumentacijos eilutė--]

</noinclude>

Įsidėmėkite:

  • Kodą <noinclude> įterpkite paskutinėje šablono eilutėje be jokio tarpo
  • Po to praleiskite vieną eilutę ir įterpkite šabloną {{Dokumentavimas}}
  • Praleidę dar vieną eilutę, pradėkite rašyti dokumentaciją
  • Po paskutinės dokumentacijos eilutės praleiskite vieną eilutę ir būtinai įrašykite kodą </noinclude>

Ką rašyti dokumentacijojeKeisti

Dokumentacijų stilius yra laisvas, tačiau kiekviena dokumentacija privalo turėti paragrafą „Naudojimas“, kuriame turi būti įterptas šablono naudojimo kodas (ir, jei reikalinga, aprašymas, kur ir kaip naudoti). Dažnai prireikia parametrų paaiškinimo skyrelio ir bent vieno pavyzdžio. Pavyzdinė dokumentacija: Šablonas:Infolentelė gama.

Kita informacijaKeisti

Kategorizavimas ir tarpkalbinės nuorodosKeisti

Pabaigus rašyti dokumentaciją, prieš kodą </noinclude> turite kategorizuoti šabloną bei įdėti tarpkalbines nuorodas.

Pagrindinė šablono kategorija yra Kategorija:Šablonai, infolentelės – Kategorija:Infolentelės, o stub-šablono – Kategorija:Nebaigtumo šablonai. Tačiau šios kategorijos yra labai abstrakčios, todėl šablonai turėtų būti kategorizuojami į smulkesnes kategorijas.

Kategorizuojant įvedamas kodas:

[[Kategorija:''Kategorijos pavadinimas'']]

Tada praleidžiama eilutė ir dokumentacija užbaigiama kodu </noinclude>.

Apie tarpkalbinių nuorodų įvedimą skaitykite puslapyje Tarpkalbinės nuorodos.

Ką dar galima rašyti dokumentacijoseKeisti

Dokumentacijose galima sukurti dar vieną antro lygio antraštę, pavadinimu „Panašūs šablonai/infolentelės“ ir ten įdėti šablonus/infolenteles, kurie yra glaudžiai susiję su dokumentuojamu šablonu/infolentele.

Kokiems šablonams dokumentacija nereikalingaKeisti

Navigaciniuose šablonuose (pvz.: {{Estijos apskritys}}) dokumentacijos nereikia, nes juose nėra jokių parametrų, o šablonai naudojami tik tuose straipsniuose, į kuriuos jie nukreipia.