Viquidites:Documentació de plantilles

Les plantilles són un element potent del MediaWiki, però poden resultar confuses pels novells i també els usuaris experimentats poden tenir dificultats per treure'n l'entrellat de les més complexes. Per millorar la facilitat d'ús, tota plantilla hauria de tenir la documentació corresponent.

La documentació de plantilla hauria d'explicar què 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 atenció en altres àrees, la pugui utilitzar correctament. Això és especialment necessari en cas de plantilles molt àmpliament utilitzades.

Què s'ha d'explicar

La documentació de la plantilla hauria d'explicar:

La descripció del propòsit bàsic de la plantilla: què fa i, si no és immediatament obvi, per què es necessita. Si hi ha unes altres plantilles amb noms o propòsits similars, és una bona pràctica indicar-les per reduir la possibilitat d'equivocar-se no utilitzant la plantilla correcta.
Els paràmetres de la plantilla: si són paràmetres numerats, amb nom o opcionals, i en aquest cas quins són els valors per defecte i quin efecte tenen. S'hauria d'explicar clarament si un paràmetre pot prendre només un conjunt limitat de valors o està limitat de qualsevol altra manera, per exemple, si només pot utilitzar: "sí", "no" o un número.
Exemples d'ús: 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 què és el que cal escriure i facilitar la còpia, com aquesta mateixa mostra. Si la plantilla es pot utilitzar de diferents maneres, per exemple amb paràmetres opcionals o sense, proporcioneu diferents exemples. Una bona manera de fer-ho és incloent la pròpia plantilla en la documentació (amb exemples reals), i cada vegada amb paràmetres diferents mostrant-los en cada cas.
Plantilles relacionades: si la plantilla forma part d'una sèrie de plantilles relacionades, afegiu els enllaços a aquestes plantilles per facilitar la navegació i amb una breu explicació de les diferències entre elles.
Categories i enllaços interwiki si n'hi ha. Igual que la documentació, 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 més adequada.

La documentació d'ús de la plantilla es posa sovint en una subpàgina de la mateixa plantilla i s'inclou al final de la pàgina de plantilla. Així se separa el codi de la plantilla, sovint complex, del text explicatiu fent més fàcil modificar-lo. Això permet també protegir les plantilles quan sigui necessari mentre queda oberta la modificació del text de la documentació per a qualsevol usuari. En cas que s'afegeixi el text de documentació en la mateixa plantilla, en utilitzar-la aquest text també s'ha de processar fent-la menys efectiva i reduint els límits imposats de procés pel MediaWiki.

En qualsevol cas, la documentació cal incloure-la dins de les etiquetes <noinclude>…</noinclude> de manera que no aparegui quan s'utilitza la plantilla en una altra pàgina.

Com crear una subpàgina de documentació d'ús

Les subpàgines de documentació d'ús de plantilla tenen un nom i un format estandarditzats per mantenir una consistència.

El nom de la subpàgina és "/ús". Per exemple, la plantilla anomenada Plantilla:X tindrà la documentació a la pàgina Plantilla:X/ús. Per crear-la, o modificar-la, es pot clicar sobre la pestanya "Documentació" que apareix en obrir una pàgina de plantilla.

El format suggerit i precarregat per la pestanya "Documentació" és el següent:

{{Subpàgina de plantilla}}
<!-- SI US PLAU, AFEGIU LES CATEGORIES AL FINAL D'AQUESTA PÀGINA -->

== Descripció ==

== Sintaxi ==

== Vegeu també ==

<includeonly>
{{ORDENA:{{PAGENAME}}}}<!-- CATEGORIES AQUÍ, GRÀCIES -->

</includeonly>

La primera línia, {{Subpàgina de plantilla}}, mostrarà un missatge explicatiu sobre aquesta pàgina amb un enllaç a la pàgina amb el codi de la plantilla.

Afegiu el text de documentació després de la primera línia. Les seccions suggerides són orientatives i es poden substituir segons faci falta. Les categories i els interwikis han d'anar sota de la línia que ho indica, deixant el comentari per mantenir l'estructura quan la pàgina 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 és necessari, però en general no caldrà afegir la clau d'ordenació dins l'enllaç de categories.

Un cop creada la subpàgina ja la podeu incloure a la plantilla (Plantilla:X en aquest exemple). Editeu la plantilla i afegiu al final del seu codi:

[--última línia de codi--]<noinclude>
{{ús de la plantilla}}
</noinclude>

Amb això s'inclourà la subpàgina /ús al final de la pàgina de la plantilla.

Important: Assegureu-vos que l'etiqueta <noinclude> comenci en la mateixa línia de l'últim caràcter de codi. Si es posa en una línia nova, en utilitzar la plantilla s'afegirà una línia al final, cosa que normalment no és desitjat.

Si la plantilla ja està protegida, demaneu a un administrador que ho faci o afegiu la plantilla {{modificació protegida}} en la pàgina de discussió de la plantilla. Si ja existeix text de documentació, categories o interwikis, traslladeu-los a la subpàgina /ús ja que és millor no tenir la documentació dividida en dues pàgines.

Si s'afegeix la plantilla {{ús de la plantilla}} sense que existeixi la subpàgina /ús, es mostrarà un enllaç addicional per a crear-la. Igualment, es precarrega l'estructura estandarditzada definida a la plantilla {{ús de la plantilla/precàrrega}}.

En cas de reanomenar la plantilla s'hauria de reanomenar també la subpàgina /ús. Els administrador disposen d'aquesta facilitat per defecte.

Per no dispersar les discussions, no es mostra la pestanya per la pàgina Plantilla Discussió:X/ús.

Plantilla en blanc

Per generar una plantilla en blanc, que després pugui ser copiada de la documentació i enganxada en una altra pàgina, utilitzeu:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Per a més informació vegeu {{Parameters}}.

Exemples

Per generar una instància de la plantilla, poblada amb els seus propis noms de propietats, utilitzeu:

({{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Per a més informació vegeu {{Parameter names example}}.

Categories i enllaços interwiki

Per posar la plantilla mateixa en una categoria, afegiu el codi [[Categoria:Nom de la categoria]] entre les etiquetes <includeonly>...</includeonly> de la subpàgina /ús.
Per crear un enllaç interwiki per a la plantilla mateixa, afegiu el codi [[CodiLlengua:Nom corresponent de la plantilla]] entre les etiquetes <includeonly>...</includeonly> de la subpàgina /ús.
La subpàgina /ús ja es categoritza a Categoria:Ús de plantilles. Normalment no cal posar altres categories.
Per fer que la plantilla posi una pàgina en una categoria (quan la pàgina inclou la plantilla), afegiu [[Categoria:Nom de la categoria]] entre les etiquetes <includeonly>...</includeonly> en la pàgina de la plantilla.

Vegeu també

{{Ús de la plantilla}} – Inclou la subpàgina de documentació d'ús en la pàgina de la plantilla
{{Subpàgina de plantilla}} – Explica que la pàgina és per documentar la informació de la plantilla
<noinclude> i <includeonly>