Aide:Documentation de modèle

Les mod�les sont accessibles en �dition par tous les contributeurs. Les nouveaux utilisateurs et m�me les utilisateurs exp�riment�s peuvent avoir des difficult�s � comprendre certains mod�les. C'est pourquoi il est n�cessaire de les documenter pour am�liorer l'utilisabilit�. La documentation doit expliquer clairement ce que fait le mod�le et comment l'utiliser. Un utilisateur sans connaissance particuli�re avec la syntaxe des mod�les de MediaWiki doit pouvoir utiliser ce mod�le correctement.

Contenu de la documentation

L'�diteur visuel demande que les documentations de mod�les utilisent la balise TemplateData.

S'il n'y a PAS de sous page de documentation, la balise TemplateData doit �tre incluse dans le param�tre contenu.
S'il existe une sous page de documentation, la balise TemplateData doit �tre plac�e obligatoirement dans la sous-page de documentation.

Utilisation

La documentation d'un mod�le peut �tre faite�:

Soit directement dans la page du mod�le,
Soit dans la sous-page /Documentation du mod�le.

Il est pr�f�rable de syst�matiquement s�parer le code (le mod�le) de sa documentation (la sous-page) pour faciliter la prise en main par les nouveaux, et �viter les mod�les bris�s dont le code a �t� cass� par une correction de documentation mal faite.

Documenter directement dans la page du mod�le

Il est possible d'inclure le contenu de la documentation directement dans le corps du mod�le. Pour ce faire, il faut placer en fin de page du mod�le�:

(...Le code Wiki du mod�le est en premier...)

<noinclude>{{Documentation|contenu=
== Utilisation ==
...
}}
<!-- Cat�gories pour le mod�le -->
</noinclude>

Notes�:

L'inclusion de la documentation dans la page du mod�le est utile lorsque le mod�le est simple.
Si le mod�le est prot�g�, le contenu de la documentation doit obligatoirement �tre d�plac� en sous-page /Documentation.
Le mod�le {{Documentation}} doit obligatoirement �tre born� avec les balises <noinclude>...</noinclude> pour �viter l'inclusion de celui-ci lors de l'appel du mod�le.
Le param�tre |contenu= ne prend pas en charge la syntaxe MediaWiki des tableaux. Pour r�soudre ce probl�me, il est n�cessaire de transformer la syntaxe MediaWiki en code HTML ou alors de transf�rer le contenu de la documentation en sous-page /Documentation.
Seuls le mod�le {{Documentation}} et les catégories sont autorisés entre les balises <noinclude>. Tout texte, modèle, bandeau ou Templatedata doit obligatoirement être placé dans le paramètre contenu.

Documenter dans une sous-page dédiée

Il faut placer la documentation en sous-page dans les cas suivants :

Le modèle est très employé et utilise des paramètres qui prennent de multiples valeurs (il faut alors réduire au minimum le contenu des balises <noinclude>...</noinclude> et surtout ne pas inclure la documentation directement dans le modèle).
Le modèle et/ou sa documentation sont particulièrement longs.
Avant de protéger un modèle, il faut déplacer sa documentation en sous-page.

L'usage d'une sous page de documentation du modèle permet aussi de séparer le code (le modèle) de sa documentation (la sous-page) pour faciliter la prise en main par les nouveaux, et éviter les modèles brisés dont le code a été cassé par une correction de documentation mal faite.

Pour documenter convenablement un modèle :

Placez en fin de page du modèle :

<noinclude>{{Documentation}}</noinclude>

Pré-visualisez ou publiez le modèle.

Ensuite, sur la page du modèle, cliquez sur le lien « créer cette sous-page » pour précharger le format de base d'une page de documentation.

Puis complétez la documentation et publiez-la.

Notes :

L'appel de {{Documentation}} permet de charger automatiquement le contenu de la sous-page /Documentation.
Le modèle {{Documentation}} doit obligatoirement être entouré par les balises <noinclude>...</noinclude> pour éviter d'être lui-même inclus lors de l'appel du modèle.
Seul le modèle {{Documentation}} est autorisé entre les balises <noinclude>. Toute catégorie, texte, modèle, bandeau ou Templatedata doit obligatoirement être placé dans la sous-page.

Exemples

Modèles bien documentés

Documentations spécifiques

Voir aussi

{{Documentation attendue}}