Ce sous-projet de documentation a pour objectif d'améliorer la documentation des infobox développées en Lua. Cette première phase du projet se limite à la description des paramètres de chaque Infobox.
La section Autres phases du projet décrit sommairement les autres phases envisagées. Elles peuvent être entreprises indépendamment et en parallèle de ce sous-projet.
Pourquoi ?
À plusieurs reprises le manque de documentation des infobox développées en Lua a été critiqué[1]Modèle:,[2]Modèle:,[3]Modèle:,[4]Modèle:,[5], mais aucun progrès sensible n'a été enregistré pour le moment.
Ce problème récurrent provient en grande partie de la décorrélation entre les infobox et les modules. Chaque fonction Lua étant potentiellement utilisable dans plus de 70 infobox, il y a une difficulté à diffuser la documentation dans toutes les infobox utilisatrices de la fonction.
Quel principe ?
La structure de la documentation doit correspondre à la structure du code — c’est-à-dire, être répartie dans les modules spécialisés — mais néanmoins être utilisable par les contributeurs de toutes les infobox.
- dans un premier temps, rédiger pour chaque fonction Lua une documentation utilisateur structurée pour être réutilisée facilement. Cette documentation se trouve au niveau du module Lua, comme dans l'exemple de la fonction website(localparam).
- dans un second temps, réutiliser dans les pages de documentation des modèles, comme pour le paramètre
site webou la propriété wikidata P856 (« Erreur Lua dans Module:Wikidata à la ligne 826 : attempt to index field 'wikibase' (a nil value). ») dans l'exemple simple Infobox Observatoire ou l'exemple plus complet Infobox Organisation2.
Mais surtout maintenir cette réutilisation même lorsqu'une fonction est modifiée alors qu'elle est utilisée par plusieurs infobox. La simple copie n'est donc pas une solution viable à long terme.
Comment faire ?
Techniquement la réutilisation se fait en :
- définissant les sections à réutiliser dans la documentation des fonctions à l'aide des balises
<section begin=Nom du fragment/>et<section end=Nom du fragment/>, - puis à insérer les passages dans la documentation des infobox avec le modèle {{Extrait}}.
Le découpage de la documentation des paramètres d'une fonction est un compromis entre la recherche de simplicité et l'insertion dans une documentation existante très disparate d'une infobox à l'autre.
Le principe de nommage des fragments est le suivant :
<nom du paramètre>_<colonne de la table de description des paramètres>
- Le nom du paramètre, correspond au nom du paramètre lorsqu'il n'est constitué que d'un seul mot, par contre lorsqu'il y a plusieurs mots les espaces sont supprimées et remplacées par une majuscule au mot suivant. Exemple : logo, légendeLogo
- L'extrait, en général une colonne de la table de description des paramètres
| Code de l'extrait | Utilisation |
|---|---|
libellé
|
Libellé de l'information dans l'infobox. Il n'est pas utilisé pour les images qui s'affichent sur toute la largeur de l'infobox. Le libellé correspond généralement au nom du paramètre avec un majuscule au début avec éventuellement une forme plurielle, lorsqu'il y a plusieurs noms de paramètre c'est généralement le premier, mais il existe de nombreuses exceptions à ces principes généraux. |
paramètre
|
Nom du paramètre pour l'infobox. Il peut y avoir éventuellement plusieurs paramètres. |
wikidata
|
Nom de la propriété wikidata, ou éventuellement des propriétés. Pour certaines informations, les propriétés peuvent être enrichies de qualificatifs. |
description
|
Description de la fonction du paramètre. Lorsqu'il y a une ou des propriétés wikidata, cette description doit être proche de la description des propriétés. Mais il est néanmoins nécessaire de préciser le fonctionnement lorsqu'il y a plusieurs valeurs. |
exemples
|
Cet extrait est affiché dans la même colonne que la description. En fonction du paramètre, les exemples peuvent être génériques ou au contraire doivent être spécifique à l'infobox.
|
Qui peut participer ?
Modèle:Article détaillé L'objectif de ce projet est que chacun puisse travailler en fonction de ses besoins et de ses connaissances. Il n'est donc pas nécessaire d'être développeur Lua pour y participer.
Où en est la mise en œuvre ?
Le tableau suivant permet de visualiser l'avancement de ce projet.
Ce tableau n'est pas exhaustif, mais présente le principe de fonctionnement de la visualisation de l'avance de ce projet :
- en colonnes les fonctions réutilisables par plusieurs infobox. Cette liste incomplète est à enrichir avec les fonctions des modules déjà listés ou par d'autres modules.
- en lignes les infobox utilisatrices des fonctions. La colonne Transclusions reste à compléter avec le nombre de transclusions de l'infobox dans des articles. L'idéal étant que ces valeurs soient mises à jour dynamiquement, si c'est possible. Cette première liste est basée sur les infobox utilisant des fonctions du module Infobox/Fonctions (obtenus par une recherche du type : \"Module:Infobox/Fonctions\" "website(" -intitle:Document), complétée par la catégorie Modèle infobox Lua utilisant Wikidata. Certaines infobox ne figurent pas dans le tableau, car elles obéissent à une logique différente pour leur documentation (Cycling race/*, Databox, ), sont obsolètes (Infobox Descriptif course cycliste, ) ou trop spécifiques (Infobox Région électorale pour l'assemblée nationale du pays de Galles, ). Les infobox avec des liens rouges correspondent à des infobox existantes mais sans pages de documentation.
- dans chaque cellule l'état d'avancement qui peut prendre les valeurs suivantes :
- Modèle:Faire lorsqu'on ignore si la fonction est utilisée par l'infobox
- Modèle:Fait lorsque la fonction est utilisée et la documentation de la fonction est complètement transcluse dans la page de documentation de l'infobox.
- Vide lorsque la fonction n'est pas utilisée par l'infobox
- Modèle:Faire lorsque la transclusion n'a pas été réalisée pour tous les paramètres, mais surtout lorsqu'il y a l'ajout ou la suppression d'un paramètre dans une fonction. C'est le point le plus délicat, un développeur qui modifie les paramètres d'une fonction doit notifier dans ce tableau la modification à propager dans les infobox. Même si c'est plus simple à réaliser qu'actuellement ce n'est pas « naturel ».
Conseils aux documentaristes de fonctions
Même si vous ignorez le fonctionnement fin de la fonction que vous décrivez, la mise en place de la liste des paramètres permet d'initier la réutilisation. Certaines infobox peuvent avoir des descriptions assez précises des paramètres qui peuvent être réutilisées au niveau de la fonction.
| Colonne | Conseils |
|---|---|
| Libellé | Le ou les libellés qui apparaissent à la gauche de la valeur. Afin de simplifier la lecture, chaque libellé est sur une ligne. Le libellé n'existe pas pour les images et reste donc vide dans le tableau des paramètres. Lorsque le libellé est modifiable par un paramètre c'est indiqué par l'utilisation du modèle {{Libellé modifiable}} qui permet d'afficher l'icône  et ce paramètre est décrit à la ligne suivante du tableau.
|
| Paramètre | Nom du paramètre pour l'infobox. Il peut y avoir éventuellement plusieurs paramètres. Le nom du paramètre est mis en forme avec la syntaxe :<code></code>. Le nom de paramètre à utiliser de préférence est affiché en gras. |
| Wikidata | La ou les propriétés wikidata utilisables et leurs qualificatifs utilisée pour l'affichage de l'infobox. Chaque paramètre ou qualificatif est listé en utilisant le modèle {{WD P}}. Les qualificatifs temporels permettent de préciser la validité temporelle des informations, leur utilisation étant fréquente, il est préférable :
|
| Description | La description commence par un paragraphe général du paramètre, qui s'il y a une propriété wikidata s'appuie sur sa description. Il est souvent utile de faire une distinction entre l'utilisation d'un paramètre et l'utilisation des propriétés wikidata.
Il peut être utile de fournir :
|
| Exemples | Modèle:... |
Conseils aux documentaristes d'infobox
Lorsque le paramètre est déjà décrit de manière classique dans la documentation, examinez attentivement si l'existant n'est pas meilleur, au moins partiellement, que la documentation que vous comptez transclure. Dans ce cas testez si le comportement est conforme à la description existante. Si vous avez la confirmation, vous pouvez « remonter » cette amélioration au niveau de la documentation de la fonction pour que toutes les infobox en profitent.
Lorsqu'une fonction a déjà été réutilisée dans une autre infobox, il suffit de recopier l'ensemble des paramètres pour l'injecter dans la nouvelle infobox, en modifiant éventuellement les exemples.
Tableau de suivi de l'avancement
Infobox de personnalités
Autres infobox
Autres phases du projet
- Synthétiser les paragraphes généraux se trouvant dans la documentation de certaines Infobox (Infobox Biographie2)
- Améliorer l'aide pour la création des infobox en Lua,
- Documenter les paramètres des infobox qui n'utilisent pas de fonctions spécifiques et s'appuient sur les parties de parts standard,
- Mettre à jour les TemplateData,