Philip : Page créée avec « link= 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... »

2022-12-13T08:22:05Z

Page créée avec « droite|150px|alt=Documentation du modèle|link= 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... »

Nouvelle page

[[Fichier:Template-info.png|droite|150px|alt=Documentation du modèle|link=]]

Les [[Aide:Modèle|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 logicielle|documentation]] doit expliquer clairement ce que fait le modèle et comment l'utiliser. Un utilisateur sans connaissance particulière avec la [[Aide:Syntaxe|syntaxe]] des modèles de [[Aide:MediaWiki|MediaWiki]] doit pouvoir utiliser ce modèle correctement.

== Contenu de la documentation ==
[[Fichier:VisualEditor-logo-fr-2.svg|right|200px|link=Wikipédia:ÉditeurVisuel|alt=Logo de l'Éditeur Visuel]]
L'[[Wikipédia:ÉditeurVisuel|Éditeur Visuel]] demande que les documentations de modèles utilisent [[Aide:TemplateData|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 <code>contenu</code>.
* 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 [[#Dans la page du modèle|directement dans la page du modèle]],
* Soit [[#En sous-page dédiée|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 :
<pre>(...Le code Wiki du modèle est en premier...)

<noinclude>{{Documentation|contenu=
== Utilisation ==
...
}}

</noinclude></pre>

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 {{m|Documentation}} doit obligatoirement être borné avec les balises <nowiki><noinclude>...</noinclude></nowiki> pour éviter l'inclusion de celui-ci lors de l'appel du modèle.
* Le paramètre <code><nowiki>|contenu=</nowiki></code> 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 {{m|Documentation}} et les catégories sont autorisés entre les balises {{balise|noinclude}}. Tout texte, modèle, bandeau ou [[Aide:Templatedata|Templatedata]] doit obligatoirement être placé dans le paramètre <code>contenu</code>.

=== 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 <nowiki><noinclude>...</noinclude></nowiki> 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 :
:<pre><noinclude>{{Documentation}}</noinclude></pre>
:Pré-visualisez ou publiez le modèle.
:Ensuite, sur la page du modèle, cliquez sur le lien « <span style="color:blue">créer cette sous-page</span> » pour précharger le format de base d'une page de documentation.
:Puis complétez la documentation et publiez-la.

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

== Exemples ==

=== Modèles bien documentés ===
* [[Modèle:Coloré]]
* [[Modèle:Icône de titre]]
* [[Modèle:Infobox Musique (œuvre)]]

=== Documentations spécifiques ===
* {{m|Documentation de carte complétée}}
* {{m|Documentation de modèle de point}}
* {{m|Documentation d'image complétée}}
* {{m|Documentation lien vers portail}}
* {{m|Documentation lien vers projet}}
* {{m|Documentation palette}}
* {{m|Documentation paramétrage de carte}}
* {{m|Documentation paramétrage de carte en sous-page}}

== Voir aussi ==
* {{m|Documentation attendue}}
<noinclude>
[[Catégorie:Aide:Modèle|Documentation]]
</noinclude>

Aide:Documentation de modèle - Historique des versions