Aiuto:Manuali dei template
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 fa un template 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 Cathopedia.
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.
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. - 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. Vedi il template {{Templateprotetto}}.
Struttura del manuale
All'interno del manuale bisognerebbe quindi trovare 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 |
|
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 "vatelapesca" ==) per spiegarne al meglio il funzionamento.
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 o sotto 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à.
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 {{MultiCol}} scrivere:
Infine tra le pagine correlate vanno inserite anche le pagine di aiuto o delle linee guida che riguardano l'uso del template.
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 | |
| Collegamenti esterni | |
|
Aiuto Manuali dei template di it.wiki: il materiale ivi presente è stato rielaborato per Chatopedia e integrato | |