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 y 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 Modèle:Balise. 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 Modèle:Balise. 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}}