Vide 'a sorgende pe Aiuto:Manuali dei template

[[File:Vocabulario manual.jpg|thumb|150px|right|I manuali si usano da secoli ma sono sempre molto utili]]I '''[[aiuto:Template|template]]''' sono una funzione molto potente del software [[MediaWiki]], ma possono risultare difficoltosi da utilizzare per i nuovi utenti e anche gli esperti potrebbero avere problemi nel capire il funzionamento dei più complessi. Per questo motivo, i template dovrebbero sempre essere dotati di un '''manuale''' d'uso, leggibile nella pagina stessa del template.

Il manuale deve spiegare cosa un template fa e come utilizzarlo, in modo sufficientemente chiaro anche per gli utenti non esperti della sintassi di programmazione dei template, non pochi anche tra i veterani di Wikipedia. 

Per quanto riguarda la struttura tutti i manuali dovrebbero il più possibile essere conformi a questa guida, per cercare di uniformarne la funzionalità e l'aspetto grafico.
{{TOC aiuto|Left}}
== Cosa inserire nel manuale ==
Il manuale di un template dovrebbe comprendere:
* Lo '''scopo''' del template: il risultato, se non ne è immediatamente ovvio, l'utilità, unitamente alla descrizione delle tipologie di pagine e voci per le quali è possibile o non è possibile l'uso.
* I '''[[Wikipedia:Template#Template parametrici|parametri]]''' del template: se è sufficiente indicarli in modo sequenziale o vanno nominati esplicitamente, se sono obbligatori o opzionali, quali sono i valori ammessi per ogni parametro, quali sono i valori predefiniti e che effetto hanno. Tutto ciò deve essere chiaramente spiegato, per tutti i parametri.
* Se il template può e/o deve essere '''[[aiuto:Subst|substato]]''' o meno.
* Gli '''esempi di utilizzo''': indicazione dell'esatto ''codice in linguaggio wiki'' che dovrebbe essere usato ed il risultato che produce. L'esempio dovrebbe essere incluso tra <code><nowiki><code>...</code></nowiki></code>, per renderlo chiaro e facile da copiare, come ad esempio:<br><code><nowiki>{{non firmato|pinco pallino|01:19, 13 set 2010}}</nowiki></code><br>Se il template può essere usato in molti modi diversi, con o senza parametri opzionali, vanno fatti gli esempi opportuni. Può essere molto utile [[Aiuto:Inclusione|includere]] il template stesso nel proprio manuale alcune volte, in diversi esempi reali, con differenti parametri, indicando gli stessi.
* Le '''pagine correlate''': se il template appartiene ad una serie, includere i wikilink agli altri template della stessa serie, al fine di rendere la navigazione più facile (un template di navigazione apposito può essere utile). Vanno comunque indicati i template simili, e le differenze in modo scegliere quello più opportuno. Infine bisogna indicare le pagine dell'aiuto, delle linee guida e di progetto utili alla comprensione delle modalità di utilizzo del template.

== Creare un manuale ==
La documentazione dei template è scritta spesso in una [[Aiuto:Sottopagina|sottopagina]] del template stesso che poi viene [[Aiuto:Inclusione|inclusa]] a sua volta alla fine del codice del template.<br>
Per creare quindi un manuale assicurarsi che nella pagina del template non sia già presente il [[template:man]] di servizio (''{{tl|man}}''). Se assente, inserirlo tra i tag <code>&lt;noinclude>&lt;/noinclude></code> (per evitare che il manuale venga poi riportato nelle pagine che usano il template), salvare la pagina e cliccare sulla scritta '''Crea le istruzioni!'''.

Si inserisce il manuale in una sottopagina perché così il codice, spesso complesso, viene separato dalla documentazione, rendendo la parte documentativa più facile da compilare e gestire. Permette inoltre una più agevole [[Wikipedia:PROTEZIONE|protezione]] del codice dei template, ove necessario, pur lasciando a chiunque la possibilità di modificare o integrare il manuale.
== Modificare un manuale==
[[File:Italian template manual edit link.png|thumb|right|Anche se il template è protetto il manuale si può sempre modificare]]
I manuali dei template si possono sempre modificare. Se è stato correttamente inserito il {{tl|man}} allora sarà presente un link per editarlo.

== Struttura del manuale ==
All'interno del manuale bisognerebbe trovare quindi queste essenziali [[Aiuto:Sezioni|sezioni]]:<br />
<code>Incipit</code><br>
<code>== [[Wikipedia:Manuali dei template#Uso|Uso]] ==</code><br />
<code>== [[Wikipedia:Manuali dei template#Parametri|Parametri]] ==</code><br />
<code>== [[Wikipedia:Manuali dei template#Esempi d'uso|Esempi d'uso]] ==</code><br />
<code>== [[Wikipedia:Manuali dei template#Note|Note]] ==</code><br />
<code>== [[Wikipedia:Manuali dei template#Pagine correlate|Pagine correlate]] ==</code><br />
<code><nowiki>[[Categoria:Manuali dei template]]</nowiki></code><br />

Iniziare la stesura del manuale scrivendo lo scopo e l'utilità per cui il template è stato creato.

=== Uso ===
Fornire dettagli sui tipi di pagine e voci nelle quali è possibile o non è possibile l'uso, e il confronto con template simili.

=== Parametri ===
Occorre spiegare il funzionamento di ogni parametro. Un buon metodo è quello di scrivere il codice del template nella forma in cui verrà usato, con a fianco la spiegazione dei parametri.<br>
Ad esempio:
{{MultiCol}}
<nowiki>{{nome del template</nowiki><br><nowiki>
|parametro1 = </nowiki><br><nowiki>
|parametro2 = </nowiki><br><nowiki>
...</nowiki><br><nowiki>
}}</nowiki>
{{ColBreak}}
<br>
*'''parametro1''' = spiegazione parametro1
*'''parametro2''' = spiegazione parametro2
:...
{{EndMultiCol}}
Per l'inserimento dei parametri, soprattutto se numerosi, si possono utilizzare i template {{tl|TabellaTemplate}} e {{tl|Parametro}} con la relativa [[Template:Parametro#Legenda_colori|tabella colori]] per assegnare le priorità.<br>
Ci sono quelli '''obbligatori''', quelli <span style="color:green">'''facoltativi'''</span>, quelli <span style="color:blue">'''consigliati'''</span> e quelli cui fare <span style="color:red">'''attenzione'''</span>, ovvero quelli in cui solo determinati valori sono accettati, per i quali se necessario è consigliato inserire una [[Aiuto:Sezioni|sottosezione]] (ad esempio <code>== Valori accettati dal parametro "pincopallino" ==</code>) per spiegarne al meglio il funzionamento.

=== Esempi d'uso ===
A volte la sola spiegazione dei parametri può non bastare a far capire come utilizzare il template.
È quindi consigliato fornire alcuni esempi pratici in cui è stato utilizzato il template creando l'intestazione <code><nowiki>== Esempi d'uso ==</nowiki></code>.<br>
Solitamente si utilizza la forma "''codice - esempio''", ovvero incolonnare a sinistra il codice così come andrebbe inserito e a destra ciò che il codice genera, ovvero il template così come si presenta sulle pagine in cui viene utilizzato.<br>
Il codice di esempio andrà chiuso tra i tag <code><nowiki><poem><code><nowiki>...&#60;/nowiki></code></poem></nowiki></code> ("''codice''") o <code><nowiki><pre>..</pre></nowiki></code> ("''pre-formattato''") per una più semplice leggibilità.<br>
Ad esempio:
{{MultiCol}}
Con il tag <code><nowiki><poem><code><nowiki>...&#60;/nowiki></code></poem></nowiki></code>
<poem><code><nowiki>{{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]]
}}</nowiki></code></poem>
Con il tag <code><nowiki><pre>..</pre></nowiki></code>
<pre>{{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]]
}}</pre>
{{ColBreak}}
{{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]]
}}
{{EndMultiCol}}
Nel caso di template eccessivamente larghi, o che occupano tutta la larghezza della pagina si può inserire il template generato di esempio al di sotto del codice di spiegazione.

=== Note ===
L'utilizzo di [[aiuto:note|note]] è consentito anche nei manuali dei template, al fine di fornire tutte le informazioni possibili.

=== Pagine correlate ===
Per facilitare la navigazione tra i template, che molte volte può risultare complessa, è consigliabile includere, sotto l'intestazione <code>== Pagine correlate ==</code>, gli eventuali template collegati a quello in oggetto. Per elencarli si consiglia l'utilizzo di un [[Aiuto:Markup#Sezioni.2C_paragrafi.2C_liste_e_linee|elenco puntato]].<br>
Ad esempio, per il template {{tl|Colonne}} scrivere:
*[[Template:Colonne spezza]]
*[[Template:Colonne fine]]

Infine tra le pagine correlate vanno inserite anche le pagine di aiuto o delle linee guida che riguardano l'uso del template.

È infine consigliabile apporre il template {{tl|Progetto}} elencando il o i [[WP:Progetto|progetti]] in cui il template rientra tematicamente, oltre al [[Progetto:Coordinamento/Template|Progetto:Template]].<br />
Ad esempio, per il template {{tl|Film}} (che viene usato nelle voci inerenti al [[Progetto:Cinema]]) scrivere:<br />
<code><nowiki>{{Progetto|Cinema|Template}}</nowiki></code><br />
per ottenere:
{{Progetto|Cinema|Template}}

Abbreviazioni (redirect) utili del nome del template possono essere riportate all'inizio del manuale tramite {{tl|abbreviazioni}}.

=== Categorizzazione ===
Ogni manuale va inserito nella categoria [[:Categoria:Manuali dei template]] scrivendo a fine pagina la stringa:<br>
<code><nowiki><noinclude>[[Categoria:Manuali dei template]]</noinclude></nowiki></code><br>
I tag <code>noinclude</code> evitano tale categorizzazione anche per le pagine in cui il template verrà inserito.

== Pagine correlate ==
*[[Aiuto:Template]]
*[[Template:Man]]

{{progetto|template}}

[[Categoria:Convenzioni di stile di Wikipedia]]
[[Categoria:Linee guida sulle pagine]]