Aide:Modèles/Comment documenter un modèle ?

Pourquoi documenter ?

Les modèles sont des pages qui acceptent des paramètres ; ces derniers sont référencés dans le code source du modèle mais ce code est souvent abscons pour ceux qui ne sont pas des « techniciens de MediaWiki ». La documentation sert donc à expliquer de manière claire (et le plus uniformément possible) l'utilisation du modèle. Elle est nécessaire car les modèles sont et doivent être utilisés par une foule de contributeurs qui ne connaissent pas les arcanes du logiciel (et a fortiori des modèles).

Où documenter ?

Puisque les pages de modèles sont utilisées en inclusion, il est préférable que le texte de celles-ci soit le plus court possible (pour limiter le traitement des pages qui les utilisent et pour accélérer la vitesse d'apparition de ces pages). D'autre part, le modèle {{m}} fait référence à la page du modèle et l'utilisateur s'attend alors à y trouver sa documentation. La documentation devrait donc être rédigée dans une sous-page du modèle incluse dans une section <noinclude>...</noinclude> de celui-ci.

De la même manière qu'un bandeau indique qu'une page utilisateur ne fait pas partie de l'espace encyclopédique ({{Page personnelle}}), un équivalent sert à identifier une page de documentation d'un modèle : {{Sous-page de documentation}}. Celui-ci implique que la sous-page de documentation doit s'appeler « Documentation ».

Comment documenter ?

Pour créer un nouveau modèle contenant le texte préchargé, utilisez le formulaire ci-dessous :

Sinon copier le texte ci-dessous dans la page du modèle :

<includeonly><!--

--><!-- Remplacez ce commentaire par le code de votre modèle --><!--

--><includeonly><noinclude>
{{Documentation}}
</noinclude>

Une fois votre page créée, cliquez sur le lien menant à la sous-page de documentation et copiez le texte ci-dessous dans cette dernière :

{{Sous-page de documentation}}

== Utilisation ==
<!-- Expliquez ici à quoi sert le modèle -->

== Syntaxe ==
<pre><nowiki>
<!-- Entrez ici la syntaxe du modèle -->
</nowiki></pre>

{|class="wikitable"
! Nom !! Obligatoire !! Par défaut !! Description 
|-
<!-- Entrez ici la description des paramètres du modèle -->
|}

== Exemple ==
<pre><nowiki>
<!-- Donnez ici un exemple d'utilisation de votre modèle -->
</nowiki></pre>
donne :
<!-- Recopiez le même exemple ici de façon à ce que l'utilisateur voie le résultat -->

<!-- Vous pouvez donner d'autres exemple le cas échéant -->

== Variantes ==
<!-- Entrez ici la liste des modèles connexes -->

== Voir aussi ==
<!-- Entrez ici la liste des pages connexes -->

[[catégorie:Modèle]]
<!-- Ajoutez ici les autres éventuelles catégories -->

Pour vous aider, n'hésiter pas à consulter la documentation d'autres modèles. Par exemple, celle du modèle {{purge}}.