|
[[Fichier:Template-info.png|droite|150px|alt=Documentation du modèle|link=]]
{{à mettre à jour}}
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.
=== Où documenter ? ===
== Contenu de la documentation ==
La documentation d’un modèle peut être faite :
{{...}}
* Soit dans la page du modèle, '''directement dans ce modèle''' : il faut placer {{m|Documentation modèle}} ou {{m|Documentation modèle compliqué}} dans la page du modèle et entre les bornes {{nobr|<code>{{Balise|noinclude}}…{{Balise|/noinclude}}</code>}}. Se reporter au [http://fr.wikipedia.org/wiki/Aide:Comment_documenter_un_modèle_%3F#Comment_documenter_directement_dans_le_mod.C3.A8le.C2.A0.3F chapitre ''Comment documenter directement dans le modèle ?'']
* Soit '''dans la sous-page <code>/Documentation</code>''' : il faut alors placer {{m|Documentation modèle vue directement}}, ou un autre {{quoi}}, dans la sous-page, entre les bornes {{nobr|<code>{{Balise|noinclude}}…{{Balise|/noinclude}}</code>}}. Se reporter au [http://fr.wikipedia.org/wiki/Aide:Comment_documenter_un_modèle_%3F#Comment_documenter_dans_la_sous-page_du_mod.C3.A8le.C2.A0.3F chapitre ''Comment documenter dans la sous-page du modèle ?'']
En apposant {{m|Documentation}} dans un modèle à documenter, vous serez assisté(e) dans la création de sa sous-page de documentation.
==== Quand doit-on placer la documentation en sous-page ? ====
Il faut documenter 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 <code>{{Balise|noinclude}}</code>…<code>{{Balise|/noinclude}}</code> et surtout ne pas inclure la documentation directement dans le modèle).
* Le modèle et/ou sa documentation sont particulièrement '''longs'''.
* On souhaite '''reprendre''' (c'est-à-dire inclure) la documentation dans une page d’aide.
* '''Avant de protéger un modèle''', il faut déplacer sa documentation en sous-page.
=== Comment documenter directement dans le modèle ? ===
Pour documenter un modèle déjà existant, [[copier-coller|copiez-collez]] et '''adaptez''' l’un des codes ci-après à la fin de la source d’un modèle (c’est-à-dire juste avant son dernier saut de ligne existant, et sans aucun autre saut de ligne inutile ajouté après).
==== Documenter un modèle simple ====
Pour un « petit » modèle, sans paramètres nommés, « sur une ligne » :
<pre><noinclude>
{{Documentation modèle}}
== 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 du modèle]] /Documentation.
<!--=== IndiquezDans quandla utiliserpage cedu 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 bas de page du modèle :
<pre><noinclude>{{Documentation|contenu=
== Syntaxe ==
<code><nowiki>{{</nowiki>{{PAGENAME}}|1|2|etc.}}</code>
* <code>1</code> : description1 (obligatoire).
* <code>2</code> : description2 (facultatif, ''défaut2'' par défaut).
* etc.
== Exemple ==
« <code><nowiki>{{</nowiki>{{PAGENAME}}|<!-- à compléter -->}}</code> » donne « {{{{PAGENAME}}|<!-- à compléter à l’identique -->}} »<!-- pour un modèle simple (sur une ligne) -->
== Variante ==
* {{M|<!-- nom de modèle connexe -->}}
== Voir aussi ==
* [[<!-- Nom de page à voir -->]]
[[Catégorie:Nom de la catégorie du modèle]]
[[en:Template:Nom du modèle anglophone équivalent]]
</noinclude></pre>
==== Documenter un modèle plus complexe ====
Pour un modèle plus complexe, avec paramètres nommés :
<pre><noinclude>
{{Documentation modèle}}
== Utilisation ==
...
}}
<!-- Indiquez quand utiliser ce modèle. -->
<!-- Catégories pour le modèle -->
== Syntaxe ==
</noinclude></pre>
Note :
* 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ée 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.
=== En sous-page dédiée ===
<nowiki>{{</nowiki>{{PAGENAME}}
Il faut documenter en sous-page dans les cas suivants :
|paramètre1=valeur1
* 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).
|paramètre2=valeur2
* Le modèle et/ou sa documentation sont particulièrement longs.
|paramètre3=valeur3
* On souhaite reprendre (c'est-à-dire inclure) la documentation dans une page d'aide.
|etc.
* Avant de protéger un modèle, il faut déplacer sa documentation en sous-page.
}}
Pour documenter convenablement un modèle, il faut placer en bas de page du modèle :
== Paramètres ==
<pre><noinclude>{{Documentation}}</noinclude></pre>
Puis cliquez sur le lien [créer] pour précharger le format de base d'une page de documentation.
Note :
* <code>paramètre1</code> : description1 (obligatoire).
* L'appel de <code><nowiki>{{Documentation}}</nowiki></code> permet de charger automatiquement le contenu de la sous-page /Documentation.
* <code>paramètre2</code> : description2 (facultatif, ''défaut2'' par défaut).
* Le modèle {{m|Documentation}} doit obligatoirement être bornée avec les balises <nowiki><noinclude>...</noinclude></nowiki> pour éviter l'inclusion de celui-ci lors de l'appel du modèle.
* <code>paramètre3</code> : description3 (optionnel, lorsque <code>paramètre2</code> est fourni, ''défaut3'' par défaut).
* etc.
== ExempleExemples ==
=== Modèles bien documentés ===
{{En-tête tableau "Code Rendu"}}
|-
|<pre><!-- Le même code --></pre>
|<!-- Le même code -->
|}
== Variante ==
* {{M|<!-- nom de modèle connexe -->}}
== Voir aussi ==
* [[<!-- Nom de page à voir -->]]
[[Catégorie:Nom de la catégorie du modèle]]
[[de:Vorlage:Nom du modèle germanophone équivalent]]
</noinclude></pre>
==== Formulaire de documentation préchargé ====
Pour disposer d’un formulaire de documentation préchargé lors de la création d’un nouveau modèle, mettez le nom de modèle de votre choix dans la boîte suivante et cliquez sur le bouton « Créer le modèle » :
<inputbox>
type=create
preload=Modèle:Préchargement de nouveau modèle
buttonlabel=Créer le modèle
default=Modèle:nom du modèle
width=40
bgcolor=#ffeeee
</inputbox>
==== Exemples de modèles bien documentés ====
* [[Modèle:Coloré]]
* [[Modèle:Icône de titre]]
* [[Modèle:TestInfobox 2Musique (œuvre)]]
* [[Modèle:Voir l'aide]] (variante)
=== Documentations spécifiques ===
=== Comment documenter dans la sous-page du modèle ? ===
[[Copier-coller|Copiez-collez]] et '''adaptez''' le code ci-après '''directement''' à la fin de la source du modèle :
<pre><noinclude>
{{Documentation}}<!-- Catégories et liens interwikis en sous-page de documentation -->
</noinclude></pre>
Puis cliquez sur le lien rouge pour éditer la page. La documentation demeure globalement semblable.
==== Documenter un modèle simple ====
<pre>{{Documentation modèle en sous-page}}
== Utilisation ==
<!-- Indiquez quand utiliser ce modèle. -->
== Syntaxe ==
<code><nowiki>{{</nowiki>{{PAGENAME}}|1|2|etc.}}</code>
* <code>1</code> : description1 (obligatoire).
* <code>2</code> : description2 (facultatif, ''défaut2'' par défaut).
* etc.
== Exemple ==
« <code><nowiki>{{</nowiki>{{PAGENAME}}|<!-- à compléter -->}}</code> » donne « {{{{PAGENAME}}|<!-- à compléter à l’identique -->}} »<!-- pour un modèle simple (sur une ligne) -->
== Variante ==
* {{M|<!-- nom de modèle connexe -->}}
== Voir aussi ==
* [[<!-- Nom de page à voir -->]]
<includeonly>
<!-- Catégories et liens interwikis du modèle -->
[[Catégorie:Nom de la catégorie du modèle]]
[[it:Template:Nom du modèle italophone équivalent]]
</includeonly>
</pre>
==== Documenter un modèle plus complexe ====
<pre>{{Documentation modèle compliqué en sous-page<nowiki>}}</nowiki>
== Utilisation ==
<!-- Indiquez quand utiliser ce modèle. -->
== Syntaxe ==
<nowiki>{{</nowiki><!-- nom du modèle -->
|paramètre1={{Param|valeur1}}
|paramètre2={{Param|valeur2}}
|paramètre3={{Param|valeur3}}
|etc.
}}
== Paramètres ==
* <code>paramètre1</code> : description1 (obligatoire).
* <code>paramètre2</code> : description2 (facultatif, ''défaut2'' par défaut).
* <code>paramètre3</code> : description3 (optionnel, lorsque <code>paramètre2</code> est fourni, ''défaut3'' par défaut).
* etc.
== Exemple ==
{{En-tête tableau "Code Rendu"}}
|-
|<pre><!-- Le même code --></pre>
|<!-- Le même code -->
|}
== Variante ==
* {{M|<!-- nom de modèle connexe -->}}
== Voir aussi ==
* [[<!-- Nom de page à voir -->]]
<includeonly>
<!-- Catégories et liens interwikis du modèle -->
[[Catégorie:Nom de la catégorie du modèle]]
[[es:Plantilla:Nom du modèle hispanophone équivalent]]
</includeonly>
</pre>
==== Exemples de modèles bien documentés ====
* [[Modèle:Wikilien/Documentation]]
=== Autres modèles spécifiques de documentation ===
* {{m|Documentation de carte complétée}}
* {{m|Documentation de modèle de point}}
* {{m|Documentation paramétrage de carte en sous-page}}
=== Voir aussi ===
* {{m|Documentation attendue}}
<noinclude>
| 