Aide:Documenter un modèle

De Poképédia
Aller à la navigation Aller à la recherche

Cette page d'aide a été rédigée de manière à contenir le plus petit nombre de liens bleus possible, afin de faciliter sa lecture.


Lors de la création d'un modèle, il est souhaitable qu'un mode d'emploi soit fourni pour le présenter aux autres contributeurs. Ce mode d'emploi est normalisé afin de s'assurer que toutes les informations nécessaires à la compréhension et à l'utilisation d'un modèle seront présentes, et qu'il est toujours tenu à jour.

Contenu de la page du modèle

Un modèle livré sans mode d'emploi peut provoquer de sérieux maux de crâne...

La page même du modèle ne devra contenir que deux choses : le code du modèle, inséré dans une balise <includeonly>, et l'inclusion de la documentation, dans une balise <noinclude>.

La documentation se trouve systématiquement sur une sous-page dédiée dont le titre suit la forme Modèle:Nom_du_modèle/Documentation. Ainsi, la source d'une page de modèle ressemble à ceci :

<includeonly>code du modèle</includeonly><noinclude>{{/Documentation}}</noinclude>

Et c'est tout : pas de bandeaux, pas de catégories. Tout est dans la page de documentation. Cette séparation permet de rendre plus lisible le code du modèle, et de laisser la documentation éditable si le modèle devait être protégé. Les modèles imbriqués, comme le modèle Apprentissage, sont des cas particuliers : leur documentation doit être réunie sur une seule et même sous-page, qui est celle de la partie commune principale de l'ensemble, les autres modèles l'incluant plutôt que d'inclure une sous-page qui leur est propre.

Commentaires

Certains modèles nécessitent des explications au sein même de leur code en raison de leur complexité. Un modèle peut être jugé complexe à partir du moment où il utilise des ParserFunctions et que plusieurs sont imbriquées (une parserfunction contenant elle-même une parserfunction). Ces explications internes sont appelées commentaires.

Ces commentaires ne sont visibles que lors de l'édition du modèle et n'apparaissent pas sur les pages où le modèle est utilisé. Pour écrire un commentaire, il suffit de l'entourer des caractères <!-- et --> : <!-- ceci est un commentaire qui ne sera visible que lors de l'édition du modèle -->.

Les commentaires se placent idéalement avant la partie nécessitant un commentaire (cette dernière étant l'imbrication de plusieurs parserfunctions).

Contenu de la sous-page de documentation

En premier lieu, un renvoi vers l'aide relative aux modèles est inséré à l'aide du modèle Renvoi Aide modèle. Ensuite, les bandeaux pertinents sont ajoutés (notamment les avertissements spécifiques aux modèles). Enfin, différentes sections doivent obligatoirement être présentes :

  • But et contexte
  • Utilisation : syntaxe et paramètres
  • Exemples
  • Modifier ce modèle

Section « But et contexte »

La première, But et contexte, présente le rôle du modèle, les informations sur son utilisation courante, comme la position (« en haut des articles »), s'il est utilisé en le substituant ({{subst:NomModèle}}) ou en l'incluant et les articles qu'il concerne.

Section « Utilisation »

La partie Utilisation contient tout d'abord une sous-section Syntaxe avec le code à utiliser pour utiliser le modèle. Un exemple avec une infobox pourrait être :

{{Infobox Objet
<!-- présentation de l'objet -->
| nom          =
| nom-tm       =
| nom-ja       =
| nom-romaji   =
| nom-en       =
| miniature    =
| image        =
| légende      =
<!-- disponibilité -->
| jeu          =
| gén-1        =
| gén-2        =
| gén-3        =
| gén-4        =
| gén-5        =
| gén-6        =
| série        =
| évènementiel =
<!-- utilisation -->
| rangement    =
| fonctionnement =
<!-- commerce -->
| prix-achat   =
| prix-revente =
}}

D'autres détails peuvent être mentionnées, comme l'importance des majuscules du nom du modèle ou de certains paramètres.

Une deuxième et dernière sous-section nommée Paramètres contient, comme son nom l'indique, la liste des paramètres, tous définis précisément. Elle commence par l'insertion du modèle Légende paramètres. Si le modèle est divisé en sections (cas des infoboxes, mais aussi des modèles imbriqués où toutes les parties du modèle incluent la même et unique documentation), alors la liste des paramètres est composée d'autant de parties. Chacune contient un tableau où chaque ligne correspond à un paramètre, avec une description, les valeurs attendues (et s'ils nécessitent une valeur particulière d'un autre paramètre pour apparaître, comme dans le cas des concours/super concours pour les attaques) ainsi que la forme attendue si elle est particulière (lien wiki, présence ou non de l'extension pour un fichier, etc). Une série d'icônes est utilisée afin d'indiquer s'ils sont facultatifs, s'ils classent l'article dans certaines catégories ou s'ils définissent des données sémantiques. Le modèle Paramètre doit être mis en œuvre pour cela. Un exemple de paramètres documentés pourrait être :

Paramètre Description
série par défaut, objet de la série principale Donnée sémantique : Objet de la série La série de jeux dans lequel est présent l'objet, par exemple Jeux principaux ou Jeux secondaires.
évènementiel par défaut, pas d'indication particulière L'objet ne peut être obtenu que lors d'évènements. Indiquer oui si c'est le cas.

Section « Exemples »

La section Exemples enfin donne un code avec des valeurs réalistes pour les paramètres et le rendu de celui-ci. Plusieurs exemples peuvent être donnés, surtout en cas de différences significatives. Enfin une liste de liens vers des articles représentatifs de l'utilisation du modèle en situation réelle termine cette section.

Section « Modifier ce modèle »

Enfin, la dernière partie obligatoire, Modifier ce modèle donne des indications à destination de ceux souhaitant modifier le modèle. Elle commence obligatoirement avec l'insertion du modèle de renvoi (créant ainsi un lien vers l'aide à la création/modification de modèles et les conventions des modèles). Le contenu est ensuite plutôt libre et permet notamment de lister les autres modèles utilisés dans le code du modèle courant et de préciser les avertissements déjà mis en bandeau concernant le modèle (comme les parsers functions utilisées ou le nombre approximatif de pages sur lesquelles le modèle est inclus) ou encore d'indiquer les classes CSS particulières mises à profit.

Facultatif : section « Voir aussi »

Une dernière partie est optionnelle : Voir aussi listant les modèles utilisés ensemble dans le cas des modèles imbriqués, ou d'autres types de pages en relation avec le modèle (projets, Poképédia:).

Catégories et liens interwikis

Après les différentes sections, les catégories et les liens interwikis sont ajoutés. Tout d'abord, les catégories concernant le modèle lui-même sont insérées dans une balise <includeonly>. Dans cette même balise doivent être placés les liens interwikis, si des équivalents sur les wikis d'Encyclopaediae Pokémonis existent. Pour finir, la documentation du modèle a droit à sa propre catégorie, Aide des modèles, placée dans une balise <noinclude> afin de ne pas catégoriser le modèle lui-même.

Pour plus d'informations sur les liens interwikis, voir Aide:Liens interwikis.

Suivi

Afin de suivre l'état des documentations des modèles, un bandeau a été créé.

Bandeau « Documentation »

Le bandeau est inséré à l'aide du modèle Documentation. Il est absent si la documentation est — théoriquement — aux normes et à jour. Dans le cas contraire, il est inclus avec les autres bandeaux sur la sous-page de documentation du modèle concerné, et indique que la documentation est absente ou à revoir. Par défaut, le bandeau liste tous les problèmes que peut rencontrer une documentation :

  • La sous-page de documentation n'existe pas (paramètre sous-page),
  • La documentation, les bandeaux, les catégories et/ou les liens interwikis ne se trouvent pas sur la sous-page de documentation (paramètre délocalisation),
  • Le code du modèle n'est pas entouré par une balise <includeonly> (paramètre includeonly),
  • La documentation ne suit pas la structure standard (définie plus haut) ou est inexistante/incomplète (paramètre structure),
  • Le modèle est complexe et il n'y a aucun commentaire (paramètre commentaire).

Tout le monde peut ajouter ce bandeau à un modèle ou modifier les valeurs des paramètres (oui ou non).

Exemples