Modification de Projet:Fondations/Documentation des modèles

__NOTOC__ __NOEDITSECTION__
{{Renvoi Article|Cette page s'inscrit dans le cadre du [[Projet:Fondations|projet Fondations]]}}<br />
<div style="float:left; width:99%; border:6px solid #fff1ba; background:#fff1ba; {{arrondi|10px}}; margin-bottom:1em;">
<div style="float:left; width:99%; margin-bottom:6px; -moz-border-radius:8px 8px 0px 0px; -webkit-border-radius:8px 8px 0px 0px; border:solid 2px #b9cce4; background:#d2e2ff; padding:5px; text-align:center; font-size:200%;">'''Projet Fondations'''</div>

<div style="float:left; width:100%;">
{{Portail Boîte
|couleur-fond=white
|couleur-bord=#b9cce4
|texte=<center>Le projet [[Projet:Fondations|Fondations]], un peu différent des projets existants ([[Projet:Citydex|Citydex]], [[Projet:Pokédex|Pokédex]] ou encore [[Projet:BaieDex|BaieDex]]), cherche à établir ou réétablir des bases complètes et stables pour '''Poképédia''', qui existe maintenant depuis plus de 3 ans. Ce travail concerne donc autant la forme (mises en page, apparence) que le contenu (articles, [[Portail:Accueil|portails]], annexes, images et vidéos), mais aussi d'autres aspects comme l'administration (technique, avec le serveur, le nom de domaine, etc. ; et humaine, avec le [[Poképédia:Comité éditorial|comité éditorial]], les ''[[Special:Liste des utilisateurs/bureaucrat|bureaucrates]]'' et les [[Special:Liste des utilisateurs/sysop|administrateurs]]), et enfin les fonctionnalités (principalement autour des [[Special:Browse|données structurées]]). Un autre projet suivra, de la même envergure, concernant cette fois le futur de Poképédia.</center>
}}
</div>

<div style="clear:both;">
<div style="float:left; width:100%;">
{{Portail Boîte
|couleur-fond=#d2e2ff
|couleur-bord=#b9cce4
|texte=<center><span style="font-size:200%;">'''Documentation des modèles'''</span></center>
}}
{{Portail Boîte
|couleur-fond=white
|couleur-bord=#b9cce4
|titre=Actuellement
|texte=Actuellement, la documentation des modèles est très souvent mauvaise. Elle est régulièrement obsolète (le modèle a été modifié, des paramètres ont été ajoutés ou retirés mais la documentation n'a pas été mise à jour) ou incomplète (absence d'exemples) quand elle n'est pas tout simplement inexistante. 

Ce manque de qualité pose plusieurs problèmes évidents : l'utilisation d'un modèle est rendue plus complexe, surtout pour les nouveaux contributeurs ou lorsque le modèle est récent, et pour des raisons difficiles à défendre (fondamentalement, la flemme) on fait potentiellement perdre du temps à tout le monde. Si des modifications sont à apporter au modèle, il est beaucoup moins pratique de le faire en devant jongler avec une liste des paramètres dont certains n'existent plus ou d'autres ne sont pas mentionnés. En bref, '''il ne doit pas y avoir de modèle sans documentation''' et c'est d'ailleurs [[Projet:Fondations/Organisation pour les propositions|le chemin pris pour les propositions]].
}}
{{Portail Boîte
|couleur-fond=#d2e2ff
|couleur-bord=#b9cce4
|texte=<center><span style="font-size:200%;">'''Documentation des modèles'''</span></center>
}}
{{Portail Boîte
|couleur-fond=white
|couleur-bord=#b9cce4
|titre=Idées <div style="float: right;"><small><nowiki>[</nowiki>[[{{TALKPAGENAME}}|discuter]]<nowiki>]</nowiki></small></div>
|texte=<h2>Comment documenter</h2>
===Contenu de la page du modèle===
La page même du modèle ne devra contenir que deux choses : le code du modèle, inséré dans une balise <code><nowiki><includeonly></nowiki></code>, et l'inclusion de la documentation, dans une balise <code><nowiki><noinclude></nowiki></code>.

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 :
<pre><nowiki>
<includeonly>code du modèle</includeonly><noinclude>{{/Documentation}}</noinclude>
</nowiki></pre>

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 [[Modèle:Apprentissage|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 [[Aide:ParserFunctions|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 <code><nowiki><!--</nowiki></code> et <code><nowiki>--></nowiki></code> : <code><nowiki><!-- ceci est un commentaire qui ne sera visible que lors de l'édition du modèle --></nowiki></code>.

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, les bandeaux pertinents sont ajoutés (notamment les [[Modèle:Avertissement Modèle|avertissements spécifiques aux modèles]]). Ensuite, différentes sections doivent obligatoirement être présentes :

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

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 (<code><nowiki>{{subst:NomModèle}}</nowiki></code>) ou en l'incluant et les articles qu'il concerne.

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

<pre style="overflow: auto;"><nowiki>{{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        =
| série        =
| évènementiel =
<!-- utilisation -->
| rangement    =
| fonctionnement =
<!-- commerce -->
| prix-achat   =
| prix-revente =
}}</nowiki></pre>

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|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 [[:Catégorie:Icône de documentation de modèle|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 [[Aide:Données sémantiques|données sémantiques]]. Le [[Modèle:Paramètre|modèle Paramètre]] doit être mis en œuvre pour cela. Un exemple de paramètres documentés pourrait être :

{{{!}} class="tableaustandard"
! scope="col" {{!}} Paramètre
! scope="col" {{!}} Description
{{!}}-
! scope="row" style="text-align: left;" {{!}} {{Paramètre|série|facultatif=par défaut, objet de la série principale|donnée=Objet de la série}}
{{!}} La série de jeux dans lequel est présent l'objet, par exemple  <tt>[[Jeux principaux]]</tt> ou <tt>[[Jeux secondaires]]</tt>.
{{!}}-
! scope="row" style="text-align: left;" {{!}} {{Paramètre|évènementiel|facultatif=par défaut, pas d'indication particulière}}
{{!}} L'objet ne peut être obtenu que lors d'évènements. Indiquer <tt>oui</tt> si c'est le cas.
{{!}}}


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.

Enfin, la dernière partie obligatoire, '''Modifier ce modèle''' donne des indications à destination de ceux souhaitant modifier le modèle. Elle permet notamment de préciser quels autres modèles sont 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 [[Aide:ParserFunctions|parsers functions utilisées]] ou le [[Spécial:Pages_liées|nombre approximatif de pages sur lesquelles le modèle est inclus]]) ou encore d'indiquer les [[MediaWiki:Common.css|classes CSS particulières]] mises à profit.

Une dernière partie est optionnelle : '''Voir aussi''' listant les modèles utilisés ensemble dans le cas des [[Aide:Modèle#Modèles imbriqués|modèles imbriqués]], une courte série de [[Aide:Modèle#Modèles apparentés|modèles apparentés]] (<code>[[Modèle:!/Archive|<nowiki>{{!}}</nowiki>]]</code>, <code>[[Modèle:!!|<nowiki>{{!!}}</nowiki>]]</code> et <code>[[Modèle:!-|<nowiki>{{!}}-</nowiki>]]</code> par exemple) ou d'autres types de pages en relation avec le modèle (projets, <tt>Poképédia:</tt>).

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

==Vérification==

Un certain nombre de vérifications devrait avoir lieu régulièrement : d'une part pour [[Modèle:Documentation|signaler l'absence de documentation]] ou d'une section, d'autre part pour s'assurer qu'elle est à jour (liste des paramètres). Elles peuvent se faire manuellement mais se retrouveraient du coup conditionnées au temps et au courage de quelques-uns. L'expérience prouvant que la flemme prend massivement le pas sur toutes les bonnes volontés du monde, un [[Projet:Fondations/Bots|nouveau bot]] a été créé et aussitôt réduit en esclavage pour ce travail. Il appose les bandeaux tels des avertissements destinés aux humains incapables. Il est aussi capable de trouver la modification n'ayant pas donné lieu à la mise à jour indispensable et détermine avec précision le voyou responsable.

Le bot est nommé [[Utilisateur:Roigada|Roigada]]. Il se charge uniquement des vérifications autour de la documentation des modèles. Il est utilisé en conjonction avec le [[Modèle:Documentation|bandeau Documentation]].

Le bandeau est inséré à l'aide du [[Modèle:Documentation|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 [[:Catégorie:Documentation à revoir|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 <code>sous-page</code>),
*La documentation, les bandeaux, les catégories et/ou les liens interwiki ne se trouvent pas sur la sous-page de documentation (paramètre <code>délocalisation</code>),
*Le code du modèle n'est pas entouré par une balise <code><nowiki><includeonly></nowiki></code> (paramètre <code>includeonly</code>),
*La documentation ne suit pas la structure standard (définie plus haut) ou est inexistante/incomplète (paramètre <code>structure</code>),
*Le modèle est complexe et il n'y a aucun commentaire (paramètre <code>commentaire</code>).

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

Le bot effectue plus précisément les vérifications suivantes :
*'''Contenu de chaque page de modèle :''' présence de la balise <code><nowiki><includeonly></nowiki></code>, présence de la balise <code><nowiki><noinclude></nowiki></code> contenant uniquement <code><nowiki>{{/Documentation}}</nowiki></code> (inclusion de la sous-page de documentation), absence de tout autre texte,
*'''Existence des sous-pages de documentation''',
*'''Respect de la structure standard des documentations :''' présence des différentes sections, présence des catégories (et usage des balises <code><nowiki><includeonly></nowiki></code> et <code><nowiki><noinclude></nowiki></code>), le tout dans le bon ordre,
*'''Paramètres du modèle :''' existence dans le modèle des paramètres documentés, paramètres du modèle tous présents dans la documentation, autant dans la section Paramètres que dans les sections Syntaxe et Exemples,
*'''Présence des [[Modèle:Avertissement Modèle|avertissements spécifiques aux modèles nécessaires]]''',
*'''Cohérence du bandeau de documentation :''' unicité du bandeau, existence des problèmes indiqués,
*'''Présence de commentaires en cas de modèle complexe'''.

Il réagit d'une façon spécifique pour chacun des cas :
*'''Mauvais contenu pour une page de modèle :''' ajout ou modification du bandeau <code>[[Modèle:Documentation|<nowiki>{{Documentation}}</nowiki>]]</code>, ajout d'un message sur la page de discussion de l'utilisateur ayant réalisé la modification fautive,
*'''Sous-page de documentation inexistante :''' ajout ou modification du bandeau <code>[[Modèle:Documentation|<nowiki>{{Documentation}}</nowiki>]]</code>, ajout d'un message sur la page de discussion de l'utilisateur ayant créé le modèle,
*'''Non-respect de la structure standard des documentations :''' ajout ou modification du bandeau <code>[[Modèle:Documentation|<nowiki>{{Documentation}}</nowiki>]]</code>,
*'''Documentation des paramètres du modèle pas à jour :''' ajout ou modification du bandeau <code>[[Modèle:Documentation|<nowiki>{{Documentation}}</nowiki>]]</code>, ajout d'un message sur la page de discussion de l'utilisateur ayant modifié les paramètres du modèle sans mettre à jour la documentation ou vice-versa,
*'''Absence des avertissements pertinents ou présence d'avertissements non-pertinents :''' mise à jour du bandeau <code>[[Modèle:Avertissement Modèle|<nowiki>{{Avertissement Modèle}}</nowiki>]]</code>,
*'''Bandeau de documentation incohérent :''' suppression des bandeaux doublons, mise à jour du bandeau <code>[[Modèle:Documentation|<nowiki>{{Documentation}}</nowiki>]]</code>,
*'''Modèle complexe sans commentaire''' : ajout ou modification du bandeau <code>[[Modèle:Documentation|<nowiki>{{Documentation}}</nowiki>]]</code>.

Roigada effectue toutes ces tâches uniquement sur les pages de l'espace de nom <tt>Modèle:</tt> et '''n'ayant pas le [[Modèle:Travail en cours|bandeau Travail en cours]]'''.
}}
</div>
</div>

<div style="clear:both">
<div style="width:99%; {{arrondi|0px 0px 8px 8px}}; border:2px solid #b9cce4; background:#d2e2ff; padding:5px; text-align:center; font-weight:bold;" class="plainlinks">
Récapitulatif des tâches<br />
<div style="margin: auto; width: 75%; text-align: left; font-weight: normal;">
*<s>Définir une structure pour la documentation des modèles,</s>
*Rédiger les pages d'aide utiles : [[Aide:Modèle|C'est quoi un modèle]], [[Aide:Création d'un modèle|Créer un modèle]], [[Aide:Documenter un modèle|Documenter un modèle]], 
*Documenter tous les modèles existants de cette façon :
**Déplacer les catégories, les liens interwiki et les documentations existantes dans la sous-page /Documentation,
**Mettre le code du modèle dans une balise <code><nowiki><includeonly></nowiki></code>, inclure la sous-page de documentation juste après dans une balise <code><nowiki><noinclude></nowiki></code>,
**Rédiger la documentation et faire le suivi à l'aide du [[Modèle:Documentation|modèle Documentation]].
*Programmer un [[Poképédia:Robot|bot]] [[Utilisateur:Roigada|redresseur de torts]].
</div>
{{Avancement|90}}
</div>

</div>

</div>

[[Catégorie:Projet:Fondations]]