Aiuto:Manuali dei template

I manuali si usano da secoli ma sono sempre molto utili

I 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. Template:TOC aiuto

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 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 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>...</code>, per renderlo chiaro e facile da copiare, come ad esempio:
  {{non firmato|pinco pallino|01:19, 13 set 2010}}
  Se il template può essere usato in molti modi diversi, con o senza parametri opzionali, vanno fatti gli esempi opportuni. Può essere molto utile 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 sottopagina del template stesso che poi viene inclusa a sua volta alla fine del codice del template.
Per creare quindi un manuale assicurarsi che nella pagina del template non sia già presente il template:man di servizio ({{man}}). Se assente, inserirlo tra i tag <noinclude></noinclude> (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 protezione del codice dei template, ove necessario, pur lasciando a chiunque la possibilità di modificare o integrare il manuale.

Modificare un manuale

Anche se il template è protetto il manuale si può sempre modificare

I manuali dei template si possono sempre modificare. Se è stato correttamente inserito il {{man}} allora sarà presente un link per editarlo.

Struttura del manuale

All'interno del manuale bisognerebbe trovare quindi queste essenziali sezioni:
Incipit
== Uso ==
== Parametri ==
== Esempi d'uso ==
== Note ==
== Pagine correlate ==
[[Categoria:Manuali dei template]]

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.
Ad esempio:

{{nome del template
|parametro1 =
|parametro2 =
...
}}

• parametro1 = spiegazione parametro1
• parametro2 = spiegazione parametro2

...

Per l'inserimento dei parametri, soprattutto se numerosi, si possono utilizzare i template {{TabellaTemplate}} e {{Parametro}} con la relativa tabella colori per assegnare le priorità.
Ci sono quelli obbligatori, quelli facoltativi, quelli consigliati e quelli cui fare attenzione, ovvero quelli in cui solo determinati valori sono accettati, per i quali se necessario è consigliato inserire una sottosezione (ad esempio == Valori accettati dal parametro "pincopallino" ==) 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 == Esempi d'uso ==.
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.
Il codice di esempio andrà chiuso tra i tag <poem><code><nowiki>...</nowiki></code></poem> ("codice") o <pre>..</pre> ("pre-formattato") per una più semplice leggibilità.
Ad esempio:

Con il tag <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]]
}}

Con il tag <pre>..</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]]
}}

commedia
Scena del poema illustrata da Gustave Doré
Autore	Dante Alighieri
1ª ed. origgenale	tra il 1304 e il 1321
Genere	Poema
Protagoniste	Dante
Otre personagge	Virgilio, Beatrice

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 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 == Pagine correlate ==, gli eventuali template collegati a quello in oggetto. Per elencarli si consiglia l'utilizzo di un elenco puntato.
Ad esempio, per il template {{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 {{Progetto}} elencando il o i progetti in cui il template rientra tematicamente, oltre al Progetto:Template.
Ad esempio, per il template {{Film}} (che viene usato nelle voci inerenti al Progetto:Cinema) scrivere:
{{Progetto|Cinema|Template}}
per ottenere:

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

Categorizzazione

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

Pagine correlate

• Aiuto:Template
• Template:Man