Les
plantilles
son un element potent del
MediaWiki
, pero poden resultar confuses pels novells i tambe els usuaris experimentats poden tenir dificultats per treure'n l'entrellat de les mes complexes. Per millorar la facilitat d'us,
tota plantilla hauria de tenir la documentacio
corresponent.
La documentacio de plantilla hauria d'explicar que fa i com cal utilitzar-la. Hauria de ser prou simple per a que un usuari sense coneixement complet de les complexitats de la sintaxi d'una plantilla, que inclou molts usuaris experimentats que centren la seva atencio en altres arees, la pugui utilitzar correctament. Aixo es especialment necessari en cas de plantilles molt ampliament utilitzades.
La documentacio de la plantilla hauria d'explicar:
- La
descripcio del proposit
basic de la plantilla: que fa i, si no es immediatament obvi, per que es necessita. Si hi ha unes altres plantilles amb noms o proposits similars, es una bona practica indicar-les per reduir la possibilitat d'equivocar-se no utilitzant la plantilla correcta.
- Els
parametres
de la plantilla: si son parametres numerats, amb nom o opcionals, i en aquest cas quins son els valors per defecte i quin efecte tenen. S'hauria d'explicar clarament si un parametre pot prendre nomes un conjunt limitat de valors o esta limitat de qualsevol altra manera, per exemple, si nomes pot utilitzar: "si", "no" o un numero.
- Exemples d'us
: especifiqueu exactament la sintaxi a utilitzar i el resultat que produeix. El text wiki es pot incloure entre les etiquetes
<code>…</code>
per deixar clar que es el que cal escriure i facilitar la copia,
com aquesta mateixa mostra
. Si la plantilla es pot utilitzar de diferents maneres, per exemple amb parametres opcionals o sense, proporcioneu diferents exemples. Una bona manera de fer-ho es incloent la propia plantilla en la documentacio (amb exemples reals), i cada vegada amb parametres diferents mostrant-los en cada cas.
- Plantilles relacionades
: si la plantilla forma part d'una serie de plantilles relacionades, afegiu els enllacos a aquestes plantilles per facilitar la navegacio i amb una breu explicacio de les diferencies entre elles.
- Categories
i
enllacos interwiki
si n'hi ha. Igual que la documentacio, aquests han d'estar dintre de les etiquetes
<noinclude>…</noinclude>
. Hi ha moltes categories disponibles per a plantilles, vegeu:
Categoria:Plantilles
i navegueu entre elles per trobar la mes adequada.
La documentacio d'us de la plantilla es posa sovint en una subpagina de la mateixa plantilla i s'inclou al final de la pagina de plantilla. Aixi se separa el codi de la plantilla, sovint complex, del text explicatiu fent mes facil modificar-lo. Aixo permet tambe protegir les plantilles quan sigui necessari mentre queda oberta la modificacio del text de la documentacio per a qualsevol usuari. En cas que s'afegeixi el text de documentacio en la mateixa plantilla, en utilitzar-la aquest text tambe s'ha de processar fent-la menys efectiva i reduint els limits imposats de proces pel MediaWiki.
En qualsevol cas, la documentacio cal incloure-la dins de les etiquetes
<noinclude>…</noinclude>
de manera que no aparegui quan s'utilitza la plantilla en una altra pagina.
Les subpagines de documentacio d'us de plantilla tenen un nom i un format estandarditzats per mantenir una consistencia.
El nom de la subpagina es "/us". Per exemple, la plantilla anomenada
Plantilla:X
tindra la documentacio a la pagina
Plantilla:X/us
. Per crear-la, o modificar-la, es pot clicar sobre la pestanya "Documentacio" que apareix en obrir una pagina de plantilla.
El format suggerit i precarregat per la pestanya "Documentacio" es el seguent:
{{Subpagina de plantilla}}
<!-- SI US PLAU, AFEGIU LES CATEGORIES AL FINAL D'AQUESTA PAGINA -->
== Descripcio ==
== Sintaxi ==
== Vegeu tambe ==
<includeonly>
{{ORDENA:{{PAGENAME}}}}<!-- CATEGORIES AQUI, GRACIES -->
</includeonly>
La primera linia,
{{
Subpagina de plantilla
}}
, mostrara un missatge explicatiu sobre aquesta pagina amb un enllac a la pagina amb el codi de la plantilla.
Afegiu el text de documentacio despres de la primera linia. Les seccions suggerides son orientatives i es poden substituir segons faci falta. Les categories i els interwikis han d'anar sota de la linia que ho indica, deixant el comentari per mantenir l'estructura quan la pagina es modifiqui en el futur. El preformat afegir un {{ORDENA:{{PAGENAME}}}} per assegurar-se que la
Plantilla:X
s'ordeni a les categories per "X" i no per "P". Canvieu {{PAGENAME}} si cal, pero en general no caldra afegir la clau d'ordenacio dins l'enllac de categories.
Un cop creada la subpagina ja la podeu incloure a la plantilla (
Plantilla:X
en aquest exemple). Editeu la plantilla i afegiu al final del seu codi:
[--ultima linia de codi--]
<noinclude>
{{us de la plantilla}}
</noinclude>
Amb aixo s'incloura la subpagina /us al final de la pagina de la plantilla.
Important
: Assegureu-vos que l'etiqueta
<noinclude>
comenci en la mateixa linia de l'ultim caracter de codi. Si es posa en una linia nova, en utilitzar la plantilla s'afegira una linia al final, cosa que normalment no es desitjat.
Si la plantilla ja esta protegida,
demaneu a un administrador
que ho faci o afegiu la plantilla
{{
modificacio protegida
}}
en la pagina de discussio de la plantilla. Si ja existeix text de documentacio, categories o interwikis, traslladeu-los a la subpagina /us ja que es millor no tenir la documentacio dividida en dues pagines.
Si s'afegeix la plantilla
{{
us de la plantilla
}}
sense que existeixi la subpagina /us, es mostrara un enllac addicional per a crear-la. Igualment, es precarrega l'estructura estandarditzada definida a la plantilla
{{
us de la plantilla/precarrega
}}
.
En cas de reanomenar la plantilla s'hauria de reanomenar tambe la subpagina /us. Els administrador disposen d'aquesta facilitat per defecte.
Per no dispersar les discussions, no es mostra la pestanya per la pagina
Plantilla Discussio:X/us
.
Per generar una plantilla en blanc, que despres pugui ser copiada de la documentacio i enganxada en una altra pagina, utilitzeu:
{{subst:#tag:pre|{{subst:Parameters|code|base= {{subst:BASEPAGENAME}}}}|style=overflow: auto;}}
Per a mes informacio vegeu
{{
Parameters
}}
.
Per generar una instancia de la plantilla, poblada amb els seus propis noms de propietats, utilitzeu:
({{subst:Parameters|demo|base= {{subst:BASEPAGENAME}}|_base=}}
Per a mes informacio vegeu
{{
Parameter names example
}}
.
- Per posar la plantilla mateixa en una categoria, afegiu el codi
[[Categoria:Nom de la categoria]]
entre les etiquetes
<includeonly>
...
</includeonly>
de la subpagina /us.
- Per crear un enllac interwiki per a la plantilla mateixa, afegiu el codi
[[CodiLlengua:Nom corresponent de la plantilla]]
entre les etiquetes
<includeonly>
...
</includeonly>
de la subpagina /us.
- La subpagina /us ja es categoritza a
Categoria:Us de plantilles
. Normalment no cal posar altres categories.
- Per fer que la plantilla posi una pagina en una categoria (quan la pagina inclou la plantilla), afegiu
[[Categoria:Nom de la categoria]]
entre les etiquetes
<includeonly>
...
</includeonly>
en la pagina de la plantilla.