Wikiforrás:Sablondokumentáció
A sablonok nagyban megnövelik a cikkírók lehetőségeit, de a kezdők számára nehezen érthetőek, és a számtalan különböző sablont és paramétert nehéz fejben tartani. Ezért fontos, hogy minden sablonhoz részletes dokumentáció tartozzon, ami leírja, mire való a sablon és hogyan kell használni, és a hasonló sablonok megtalálását is megkönnyíti.
Mi szerepeljen a dokumentációban?
szerkesztés- Mindenekelőtt a sablon célja: mit csinál a sablon, és (ha nem magától értetődő) mi értelme azt csinálni. Ha van idevágó irányelv, útmutató vagy segítség lap, említsd meg. Ha vannak erre a feladatra más sablonok is, említsd meg őket és mondd meg, miben különbözik ez a sablon a többitől; így kisebb az esélye, hogy a rossz sablont használja valaki.
- A sablon paraméterei. Írd le, hogy milyen paramétereket lehet használni, mik a névtelen paraméterek, mely paraméterek opcionálisak és mi az alapértelmezett értékük (ha van). Ha van valami kötelező vagy jellemző használati módja az egyes paramétereknek (pl. csak szám lehet; ha belső linket akarsz, kézzel kell beleírni), add meg azt is.
- Példák. Adj néhány példát, hogyan kell használni, és az mit eredményez. Ha a sablonnak sok paramétere van, csinálj egy konkrét értékek nélküli, másolható mintát a <tt>...</tt> vagy a <pre>...</pre> használatával.
- Kapcsolódó sablonok: ha a sablon több, együtt használandó vagy hasonló funkciójú sablon egyike, mindig linkelj a többi sablonra, hogy megkönnyítsd a navigációt. Ha elég sok sablonról van szó, érdemes külön navigációs sablont csinálni erre a feladatra. (Lásd például az angol Protection templates sablont.) A sablonok megadásához érdemes az
{{sl}}sablont használni.
Hogyan írj dokumentációt?
szerkesztésAz egyszerűbb megoldás, ha simán beírod a dokumentáció szövegét, a kategóriákat és az interwikilinkeket a sablon végén elhelyezett <noinclude>...</noinclude> blokkba, hogy csak a sablon saját lapján jelenjen meg, a sablon használatakor ne. (Ügyelj rá, hogy a <noinclude> ne új sorban kezdődjön, hanem az utolsó nem üres sor végén! Máskülönben a sablon használatakor több üres hely lesz utána, mint szeretnéd.) Ha a sablon a saját lapján csúnyán jelenik meg (például mert nincsenek megadva a paraméterek, amik a megjelenését szabályozzák), beleteheted a kódját egy <includeonly>...</includeonly> blokkba (de a dokumentációt nem!), hogy csak beillesztéskor jelenjen meg, a sablon saját lapján ne.
A bonyolultabb megoldás a dokumentációs allap használata, ilyenkor a dokumentáció a Sablon:Sablonneve/inf lapról lesz beillesztve. Ennek számos előnye van:
- mind a sablon, mind a dokumentáció szövege áttekinthetőbb lesz;
- nem áll fenn a veszélye, hogy a dokumentáció átírása közben véletlenül elrontja valaki a sablont;
- a dokumentáció akkor is szerkeszthető, ha a sablon le van védve;
- a dokumentáció nem növeli a sablont (ami nem lehet tetszőlegesen nagy – lásd en:Wikipedia:Template limits);
- a MediaWiki fordítójának nem kell a dokumentáció minden egyes változtatásakor ellenőriznie, hogy a sablon változott-e.
Hátránya viszont, hogy a sablonokat tartalmazó kategóriák könnyen elavulttá válhatnak, mert a dokumentációs lapon végrehajtott változtatások csak akkor jelennek meg a kategórialapokon, ha a dokumentálandó sablont is megváltoztatja valaki.
Dokumentációs allap használatához a sablon végére a <noinclude>{{sablondokumentáció}}</noinclude> szöveget írd be. (Ilyenkor is ügyelj rá, hogy a <noinclude> ne új sorban kezdődjön!) A sablon elmentése után megjelenő doboz "szerkeszt" gombjára kattintva szerkesztheted a dokumentációs allapot. Az interwikilinkeket és kategóriákat ilyenkor a dokumentációs allap végén egy <includeonly>...</includeonly> blokkba zárd, hogy csak a sablonra vonatkozzanak, az allapra ne.
Példa
szerkesztésA Cite web sablon példa egy allappal dokumentált sablonra.