Ajuda: manuals de plantilles
Les plantilles són una característica molt potent del programari MediaWiki , però poden ser difícils d’utilitzar per als nous usuaris, i fins i tot els experts poden tenir problemes per entendre com funcionen els més complexos. Per aquest motiu, les plantilles sempre haurien de venir amb un manual d’ usuari, llegible a la mateixa pàgina de plantilles.
El manual ha d’explicar què fa una plantilla i com utilitzar-la, d’una manera prou clara, fins i tot per a usuaris que no siguin experts en sintaxi de programació de plantilles, ni tan sols entre veterans de la Viquipèdia.
Pel que fa a l'estructura, tots els manuals haurien de complir al màxim aquesta guia per intentar estandarditzar la seva funcionalitat i aspecte gràfic.
 - Taulell d'informació |
Què cal incloure al manual
Un manual de plantilla ha d’incloure:
- El propòsit de la plantilla: el resultat, si no és immediatament obvi, la utilitat, juntament amb la descripció dels tipus de pàgines i elements per als quals és possible o no utilitzar.
- Els paràmetres de la plantilla: si n’hi ha prou amb indicar-los seqüencialment o s’han d’anomenar explícitament, si són obligatoris o opcionals, quins són els valors permesos per a cada paràmetre, quins són els valors per defecte i quin efecte tenen. Tot això s’ha d’explicar clarament, per a tots els paràmetres.
- Si la plantilla pot i / o s’ha de subestablir o no.
- Exemples d’ús : indicació del codi d’idioma wiki exacte que s’hauria d’utilitzar i del resultat que produeix. L'exemple s'ha d'incloure entre
<code>...</code>, per deixar-lo clar i fàcil de copiar, com ara:
{{non firmato|pinco pallino|01:19, 13 set 2010}}
Si la plantilla es pot utilitzar de moltes maneres diferents, amb o sense paràmetres opcionals, s’han de donar exemples adequats. Pot ser molt útil incloure la mateixa plantilla al manual algunes vegades, en diversos exemples reals, amb paràmetres diferents, que indiquin el mateix. - Pàgines relacionades : si la plantilla pertany a una sèrie, incloeu els wikilinks a les altres plantilles de la mateixa sèrie, per tal de facilitar la navegació (pot ser útil una plantilla de navegació especial). No obstant això, cal indicar plantilles similars i les diferències per triar la més adequada. Finalment, cal indicar les pàgines d’ajuda, pautes i projectes útils per entendre com utilitzar la plantilla.
Crear un manual
La documentació de la plantilla sovint s’escriu en una subpàgina de la pròpia plantilla que després s’inclou al final del codi de la plantilla.
Per crear un manual, assegureu-vos que la pàgina de la plantilla no estigui present a la plantilla: service man ( {{ man }} ). Si no hi és, inseriu-lo entre les <noinclude></noinclude> (per evitar que el manual es mostri a les pàgines que utilitzen la plantilla), deseu-la i feu clic a la paraula Crea instruccions. .
El manual s’insereix en una subpàgina perquè d’aquesta manera el codi sovint complex se separa de la documentació, cosa que facilita la compilació i la gestió de la part de documentació. També permet una protecció més fàcil del codi de plantilla, si cal, i deixa a qualsevol persona la possibilitat de modificar o integrar el manual.
Editeu un manual
Els manuals de plantilles sempre es poden editar. Si heu introduït correctament {{ man }}, hi haurà un enllaç per editar-lo.
Estructura del manual
Per tant, dins del manual hauríeu de trobar aquestes seccions essencials:
Incipit
== Uso ==
== Parametri ==
== Esempi d'uso ==
== Note ==
== Pagine correlate ==
[[Categoria:Manuali dei template]]
Comenceu a escriure el manual escrivint el propòsit i la utilitat per als quals es va crear la plantilla.
Ús
Proporcioneu detalls sobre els tipus de pàgines i d’elements en què l’ús és possible o no, i la comparació amb plantilles similars.
Paràmetres
Cal explicar el funcionament de cada paràmetre. Un bon mètode és escriure el codi de la plantilla en la forma en què s’utilitzarà, amb una explicació dels paràmetres al costat.
Per exemple:
{{nom de la plantilla
| paràmetre1 =
| paràmetre2 =
...
}}
- paràmetre1 = explicació del paràmetre1
- paràmetre2 = explicació del paràmetre2
- ...
Per introduir paràmetres, sobretot si n’hi ha molts, podeu utilitzar les plantilles {{ TableTemplate }} i {{ Parameter }} amb la taula de colors relativa per assignar prioritats.
N’hi ha d’ obligatoris , opcionals , recomanables i a tenir en compte , és a dir, aquells en què només s’accepten determinats valors, per als quals, si cal, es recomana inserir una subsecció (per exemple == Valori accettati dal parametro "pincopallino" == ) per explicar millor com funciona.
Exemples d'ús
De vegades, l'explicació dels paràmetres per si sola pot no ser suficient per deixar clar com utilitzar la plantilla. Per tant, es recomana proporcionar alguns exemples pràctics on es va utilitzar la plantilla creant la capçalera == Esempi d'uso == .
Normalment s'utilitza la forma " codi - exemple ", és a dir, a l'esquerra el codi tal com s'ha d'inserir i a la dreta el que genera el codi, és a dir, la plantilla tal com apareix a les pàgines en què s'utilitza.
L'exemple de codi s'inclourà a <poem><code><nowiki>...</nowiki></code></poem> (" codi ") o <pre>..</pre> (" pre -formatted ") per facilitar la llegibilitat.
Per exemple:
Amb l’ <poem><code><nowiki>...</nowiki></code></poem>
{{Libro
|titolo=commedia
|titoloalfa=Divina Commedia
|immagine=Gustave Doré - Dante Alighieri - Inferno - Plate 18 (Canto V - Dante has a touch of the vapours).jpg
|didascalia=Scena del poema illustrata da<br>[[Gustave Doré]]
|autore=[[Dante Alighieri]]
|annoorig=tra il [[1304]] e il [[1321]]
|genere=[[Poema]]
|protagonista=[[Dante]]
|altri_personaggi=[[Virgilio]], [[Beatrice]]
}}
Amb l’ <pre>..</pre>
{{Llibre
| títol = comèdia
| titoloalfa = Divine Comedy
| image = Gustave Doré - Dante Alighieri - Inferno - Plate 18 (Canto V - Dante té un toc dels vapors) .jpg
| llegenda = Escena del poema il·lustrat per <br> [[Gustave Doré]]
| autor = [[Dante Alighieri]]
| annoorig = entre [[1304]] i [[1321]]
| gènere = [[Poema]]
| protagonista = [[Dante]]
| altres_caràcters = [[Virgili]], [[Beatrice]]
}} | comèdia | |
|---|---|
 Gustave Doré | |
| Autor | Dante Alighieri |
| 1a ed. original | entre 1304 i 1321 |
| Tipus | Poema |
| Protagonistes | Dante |
| Altres personatges | Virgili , Beatrice |
En el cas de plantilles que són excessivament amples o que ocupen tota l'amplada de la pàgina, podeu inserir la plantilla generada com a exemple a sota del codi d'explicació.
Nota
L'ús de notes també està permès als manuals de plantilla, per tal de proporcionar tota la informació possible.
Pàgines relacionades
Per facilitar la navegació entre les plantilles, que sovint pot ser complexa, és recomanable incloure, a l'encapçalament == Pagine correlate == , qualsevol plantilla enllaçada amb la que es tracti. Es recomana l'ús d'una llista amb vinyetes per incloure-les .
Per exemple, per a la plantilla {{ Columnes }} escriviu:
Finalment, entre les pàgines relacionades, també s’han d’inserir pàgines d’ajuda o pautes sobre l’ús de la plantilla.
Finalment, és recomanable afegir la plantilla {{ Projecte }} en què es mostren els projectes en què es troba temàticament la plantilla, a més del Projecte: Plantilla .
Per exemple, per a la plantilla {{ Pel·lícula }} (que s'utilitza en els elements relacionats amb el Projecte: Cinema ) escriviu:
{{Progetto|Cinema|Template}}
obtenir:
Les abreviatures útils (redireccions) del nom de la plantilla es poden informar al principi del manual mitjançant {{ abreviatures }}.
Classificació
Cal inserir cada manual a la categoria: Manuals de plantilla escrivint la cadena al final de la pàgina:
<noinclude>[[Categoria:Manuali dei template]]</noinclude>
Les etiquetes sense noinclude eviten aquesta categorització fins i tot per a les pàgines en què s’inserirà la plantilla.