Wikipédia :Documentation sur les modèles

Un article de Wikipédia, l'encyclopédie libre
Aller à la navigation Aller à la recherche

Les modèles sont une fonctionnalité très puissante de MediaWiki , mais peuvent être déroutants pour les nouveaux utilisateurs et même les utilisateurs expérimentés peuvent avoir des difficultés à comprendre les plus complexes. Les modèles doivent donc être accompagnés d' une documentation pour améliorer la convivialité.

La documentation du modèle doit expliquer ce que fait un modèle et comment l'utiliser. Il devrait être suffisamment simple pour qu'un utilisateur sans connaissance complète des subtilités de la syntaxe du modèle - qui comprend de nombreux contributeurs expérimentés qui concentrent leur attention ailleurs - puisse l'utiliser correctement. Cela est particulièrement vrai dans le cas de modèles très largement utilisés.

Les éditeurs doivent s'en remettre aux politiques ou directives officielles lorsque les pages de documentation des modèles ne sont pas conformes aux normes et principes communautaires établis. Les éditeurs doivent également éviter de « citer » les pages de documentation des modèles comme s'il s'agissait de politiques, y compris ce guide pratique . Les pages de documentation des modèles peuvent être rédigées sans trop de débats, voire aucun, contrairement aux politiques de Wikipédia qui ont été minutieusement approuvées par la communauté (voir WP : Consensus local pour plus de détails).

Quoi inclure

La documentation du modèle doit couvrir :

  • L' objectif fondamental du modèle : ce qu'il fait et si ce n'est pas immédiatement évident, pourquoi il doit être fait. S'il existe d'autres modèles avec des noms ou des objectifs similaires, c'est une bonne idée de les mentionner, afin de réduire le risque que le mauvais modèle soit utilisé. Incluez des limitations importantes , telles que le manque de {{ visibilité de la Navbox }} sur le site Web mobile, si un modèle ne doit être utilisé que pour certains pays ou périodes, ou d'autres éléments que les éditeurs doivent connaître avant de choisir d'utiliser le modèle.
  • Les paramètres du modèle : s'ils sont numérotés, nommés ou facultatifs, et si oui, quelles sont les valeurs par défaut et quel effet elles ont. Si un paramètre ne peut prendre qu'un ensemble limité de valeurs ou est contraint de quelque manière que ce soit, par exemple s'il ne peut utiliser que "oui", "non" ou un nombre, cela doit être clairement expliqué.
  • Exemples d'utilisation : spécifiez le wikitext exact qui doit être utilisé et le résultat qu'il produit. Le wikitext peut être enfermé dans un <code>...</code>conteneur, pour le rendre clair et easy to copy, like this. Si le modèle peut être utilisé de plusieurs manières, avec ou sans paramètres facultatifs, par exemple, fournissez une série d'exemples. Une bonne façon de le faire est de transclure le modèle lui-même dans la documentation à quelques reprises (c'est-à-dire d'utiliser des exemples réels), avec des paramètres différents à chaque fois et de lister les paramètres utilisés dans chaque cas. Avec Template:Xpd, cela peut être fait sans mettre l'appel de modèle deux fois dans le wikitext.
  • Balises TemplateData : Voir Wikipedia:TemplateData/Tutorial .
  • Modèles associés : si le modèle fait partie d'une série de modèles, incluez des liens vers ceux-ci - en particulier, assurez-vous que chaque modèle de la série est lié à chacun des autres, car cela facilite la navigation. (Un modèle de navigation séparé peut être utile à cette fin, voir : Modèle : Modèles de protection ).
  • Catégories le cas échéant ( les liens InterWikimedia doivent être listés sur Wikidata – plus d'informations sur Wikipedia:Wikidata ). Comme la documentation, les catégories doivent être répertoriées dans un<noinclude>...</noinclude>conteneur sur un modèle, ou dans<includeonly>{{Sandbox other||...}}</includeonly>des balises si elles sont placées sur une page de documentation. De nombreuses catégories de templates sont disponibles, voir : Category:Wikipedia templates pour les parcourir.

Wikipédia en anglais est une source de modèles pour des centaines d'autres Wikipédias et projets apparentés. Souvent, les modèles sont entièrement autonomes, donc le processus est simple : le contenu est simplement copié sur une nouvelle page de modèle sur l'autre wiki, et tout fonctionne. Cependant, sur des modèles plus complexes, le modèle peut invoquer un module, exclure d'autres modèles, ne fonctionner que s'il est associé à un modèle distinct ou nécessiter un code CSS ou JavaScript particulier pour fonctionner. Dans ces cas, il est utile d'inclure une brève liste de modèles ou d'autres codes requis par celui-ci, à la fin de la documentation.

Où le placer

La page d'un modèle dans l' espace de noms Template est l'emplacement du code du modèle qui contrôle l'apparence et le comportement de ce modèle. Ce qui apparaît généralement sous le titre sur la page Modèle rendu : (par opposition à la fenêtre d'édition de l'onglet Éditer ou, dans le cas des modèles dont le code est protégé, l' onglet Afficher la source , est le modèle rendu lui-même, suivi d'un section pour afficher la documentation rendue du modèle, suivie des catégories auxquelles le modèle appartient.

Cependant, le wikicode modifiable pour la documentation du modèle est souvent placé sur une sous- page distincte du modèle lui-même, qui est ensuite transclus à la fin de la page du modèle. Cela sépare le code du modèle souvent complexe de la documentation, ce qui facilite la modification de la documentation et réduit le nombre d'erreurs d'édition accidentelles dans le code du modèle. Il permet également de protéger les modèles si nécessaire, limitant l'accès à l'édition du code des modèles importants tout en permettant à quiconque de modifier la documentation de ces modèles. Cette méthode est parfois appelée "modèle de page template-doc".

La documentation de tout type sur une page de modèle (y compris TemplateData ) doit toujours être entourée d'un <noinclude>...</noinclude>conteneur, afin qu'elle n'apparaisse pas lorsque le modèle est utilisé sur une autre page.

Comment créer une sous-page de documentation

Mettre la documentation dans le modèle

Vous devez mettre {{ documentation }} lors de la création (publication) d'un modèle. Ensuite, une page de documentation est créée avec [view] [edit] [history] [purge]des liens. Vous pouvez créer et modifier la documentation du modèle en cliquant sur le [edit]lien de ce volet.

Les sous-pages de documentation de modèle utilisant {{ documentation }} sont nommées et formatées en utilisant le modèle général suivant, par souci de cohérence.

Supposons que votre modèle s'appelle Template:X. Modifiez le modèle et ajoutez ce qui suit à la fin du code du modèle, ou utilisez {{subst : doc-code }} :

[--dernière ligne du code de votre modèle--] <noinclude>
{{Documentation}}
<!-- Ajoutez des catégories à la sous-page /doc et aux interwikis dans Wikidata, pas ici ! -->
</noinclude>

Cela transclurea {{ documentation }} au bas de la page du modèle.

Important : Assurez-vous que l'ouverture <noinclude>commence immédiatement après le dernier caractère du code ou du texte du modèle et non sur une nouvelle ligne, ni avec des espaces intermédiaires. Sinon, un espace supplémentaire sera inséré sous le modèle lorsqu'il est utilisé, ce qui n'est généralement pas souhaité.

Si le modèle est déjà protégé, demandez à un administrateur de le faire ou demandez une modification en utilisant un sur la page de discussion du modèle. Si la documentation et les catégories existent déjà dans une section, incluses dans un conteneur, déplacez-les dans la sous-page de documentation (où elles doivent être incluses dans ), car il est préférable de ne pas répartir la documentation sur deux pages distinctes. {{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>

Création automatique

Utilisez [create]le lien au bas de la boîte de documentation vide pour créer automatiquement une sous-page de documentation préchargée . Insérez la documentation après la première ligne et les catégories sous la ligne de commentaire appropriée - en laissant le commentaire en place, afin que la mise en page soit préservée lorsque la page sera modifiée à l'avenir. Les modèles associés, la page de politique, les projets, etc. peuvent être liés en ajoutant une section "Voir aussi". Enregistrez la sous-page.

Création manuelle

Pour créer la sous-page de documentation manuellement, créez une sous-page avec le nom Template:X/doc. Voir les détails sur {{ Documentation subpage }} ou démarrer la page en copiant-collant le texte wiki standard suivant :

{{ Documentation  subpage }} 
<!-- Ajouter des catégories aux endroits indiqués au bas de cette page et des interwikis sur Wikidata -->
== Utilisation ==


<includeonly> {{ bac à sable  autre || 
<!--  Catégories  sous  cette  ligne ;  interwikis  sur  Wikidata  -->

}} </includeonly>

La ligne du haut affichera un message expliquant la page actuelle et un lien vers la page modèle. Enregistrez la sous-page et suivez les instructions de la section " Utiliser un modèle : documentation ".

Avec TemplateData

Au lieu d'écrire manuellement un graf principal et une table d'utilisation, le modèle {{ Format TemplateData }} peut faire la majeure partie du travail. Écrivez simplement votre TemplateData dans l'interface de la table, puis encapsulez-le dans un appel de modèle comme {{Format TemplateData|1=<templatedata>...</templatedata>}}en haut de la page.

Remarques

Vous souhaiterez peut-être rediriger la page de discussion de la sous-page /doc vers la page de discussion du modèle lui-même. Ensuite, toutes les discussions relatives au modèle et à sa documentation se retrouveront sur la même page de discussion. Par exemple, redirigez Template talk:X/docvers Template talk:X.

Une page de documentation peut également être redirigée vers la sous-page /doc d'un autre modèle, si cela couvre l'utilisation des deux modèles. Dans ce cas, cliquer sur les liens pour afficher ou modifier la documentation ouvrira directement la cible de la redirection. S'il est nécessaire d'accéder à la redirection elle-même (par exemple pour supprimer la redirection et créer une page de documentation distincte), accédez à l'URL du modèle en cliquant dans la barre d'adresse en haut de votre navigateur et ajoutez /doc à la fin.

Vierge

Pour générer un modèle vierge, qui peut ensuite être copié depuis la documentation et collé dans une autre page, utilisez :

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Exemples

Pour générer une instance du modèle, remplie avec ses propres noms de propriété, utilisez :

{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Catégories et liens interwiki

  • Pour placer le modèle lui-même dans une catégorie , ajoutez le [[Category:Category name]]code dans une <includeonly>...</includeonly>section de la sous-page de documentation .
  • Pour créer un lien interwiki pour le modèle lui-même , allez sur Wikidata et suivez les instructions pour ajouter des liens vers des pages.
  • Pour placer la sous-page de documentation dans une catégorie , ajoutez le [[Category:Category name]]code dans une <noinclude>...</noinclude>section de la sous-page de documentation .
  • Pour que le modèle place un article dans une catégorie (lorsque l'article inclut le modèle), ajoutez le [[Category:Category name]]code dans une <includeonly>...</includeonly>section de la page du modèle. Le placement exact dans le code du modèle peut affecter la façon dont le code de catégorie est exécuté.

/sandbox et /cas de test

Avant de modifier un modèle, il peut être judicieux de copier d'abord le code du modèle dans un bac à sable et d'exécuter des cas de test, car le modèle peut être visible sur des milliers, voire des millions de pages. Si vous créez des sous-pages nommées exactement " /sandbox " et " /testcases " dans un modèle, la {{documentation}}case verte sur le modèle le détecte automatiquement et affiche des liens vers ces pages dans son en-tête. Pour plus d'informations, consultez Wikipedia : modèle de bac à sable et cas de test.

Plusieurs modèles, une seule page de documentation

Lorsque plusieurs modèles fonctionnent ensemble ou sont très similaires, il est souvent plus clair et plus facile de conserver une seule page de documentation qui les documente ensemble. La manière la plus simple de procéder consiste à créer une page de documentation complète sur l'un des modèles, puis à effectuer des "redirections logicielles" à partir des autres modèles. Voir, par exemple : {{ wrap }}.

Directement sur une page modèle

Lorsqu'une sous-page de documentation n'a pas été créée et que le modèle {{ documentation }} est utilisé avec un |content=paramètre sur la page de modèle réelle, alors pour placer le modèle lui-même dans une catégorie, ajoutez [[Category:Category name]]-le à l'intérieur du modèle de documentation, après le contenu. Par exemple, pour le placement sur la page de modèle réelle :

<!--Dernière ligne du code de votre modèle--> <noinclude> 
{{ Documentation 
 |  contenu  = 
<!--  documentation du modèle  --> 

[[ Catégorie : Nom de la catégorie  ]] [[ Catégorie : Nom de la catégorie2 ]] }} </noinclude >
 

Lorsqu'aucune documentation n'est nécessaire

Lorsqu'un modèle tel qu'il est affiché est lié à une page pouvant servir de documentation, une documentation distincte est superflue et n'a pas besoin d'être créée. Par exemple, un modèle de stub, utilisant le modèle {{ asbox }} comme base, affichera déjà une documentation commune préchargée pour tous les modèles de stub utilisant ce modèle, et n'aura pas besoin de documentation supplémentaire.

Trucs et astuces

Voici quelques conseils pour faciliter la rédaction de documentations :

  • Des liens vers des modèles tels que {{ Japanese year |1800}} peuvent être insérés en écrivant {{ tlp |Japanese year|1800}} . Voir {{ tlp }} pour des modèles similaires.
  • Les balises HTML comme <ref group="note">...</ref>peuvent être facilement insérées avec {{ tag }}. Cet exemple est écrit comme {{ tag |ref|params=group="note"}}
  • Le signe égal = peut être inséré avec {{=}} . Par exemple, {{ Citation required |date=1900-02-29}} est créé par {{ tlp |Citation required|date{{=}}1900-02-29}} . Évitez la notation équivalente = ce qui n'est pas facile à lire pour les autres éditeurs.
  • N'oubliez pas la <nowiki />balise unique. [[ <nowiki />exemple]] devient [[exemple]], et [ <nowiki />http://en.wikipedia.org pas de lien] est [ http://en.wikipedia.org pas de lien]. Voir WP:NOWIKI pour les détails.
  • Pour un lien vers une catégorie, utilisez {{ cat }}. Par exemple, {{ cat |Templates with incorrect parameters syntax}} devient Category:Templates with incorrect parameters syntax .
  • Pour supprimer la catégorisation des pages /sandbox et /testcases du modèle (si elles existent), utilisez ce code au bas de la sous-page de documentation :
<includeonly> {{ bac à sable  autre || {{ cas de test  autre || 
<!--  Catégories  en dessous de  cette  ligne ,  s'il vous plait ;  interwikis  sur  Wikidata  -->

}}}} </includeonly>
  • Lorsque le modèle est une infobox enfant , la documentation apparaît brisée. Empêchez cela en ajoutant la balise <includeonly> :
{{Certains modèles d'infobox (enfant)
| enfant = <includeonly>oui</includeonly>
| label1 = Bonjour
| data1 = Monde
}}<noinclude>{{documentation}}</noinclude>

Voir également