Discussion Projet:Fondations/Documentation des modèles

Pas compris

Bonjour, je n'ai pas très bien compris ce qu'il faut faire ( exactement ). Il faut rejoindre un projet, créer un projet ? j'aurais besoin d'information clair s'il vous plaît. 6 mai 2011 à 16:31 commentaire non-signé par Zekram^(d), le 6 mai 2011 à 12:22

Il faudrait que tu te trouves une véritable signature...

Il s'agit de trouver des idées de documentations de modèles. Tout est expliqué, je pense, et j'aurai du mal à t'en dire plus.

Kathan — 6 mai 2011 à 10:39 (UTC)

Grossièrement, la situation actuelle est expliquée (section « Actuellement ») et elle est assez peu joyeuse. Il y a d'ailleurs un certain nombre d'idées proposées (section « Idées ») pour améliorer ça.

Que faut-il faire ? Simplement discuter des idées proposées ici (si des choses ne vous semblent pas utiles, que l'on peut faire mieux, etc.), sur cette page de discussion, ou en proposer de nouvelles dans un premier temps. Plus tard, il s'agira d'appliquer ce qui a été décidé.

--Misdre 6 mai 2011 à 11:07 (UTC)

Des idées ? Comme par exemple, des solutions des jeux ? j'aimerai bien comprendre quelle genre d'idées. Zekram^(d) 6 mai 2011 à 16:33 (UTC)

Permets-moi une question innocente... As-tu lu la page ?

Elle est centrée sur la création de la documentation des modèles, qui est actuellement (n'ayons pas peur des mots) ridicule. Donc, Misdre voudrait des idées de documentation efficace. Documentation = Fonctionnement des modèles

Kathan — 6 mai 2011 à 16:36 (UTC)

Non, pas ce genre d'idées. C'est vrai que c'est difficile de voir de de quoi on parle vu que les modèles restent une utilisation assez avancée. Dis-toi qu'un modèle, c'est quelque chose que tu peux insérer dans d'autres articles. Tu vois les encadrés à droite de tous les articles Pokémon ? C'est un modèle. Pour savoir comment l'ajouter, il y a besoin d'une documentation. Or, il y a des modèles qui n'en ont pas, ou alors elle est très incomplète, et c'est difficile de savoir comment les utiliser. L'idée de ce projet, c'est de trouver ce qu'il faut pour écrire une bonne documentation complète (par exemple : il faut une explication pour dire à quoi le modèle sert, il faut des exemples pour voir ce que ça affiche, etc).

Ce n'est pas grave si tu n'as pas d'idées ou si tu ne comprends pas trop de quoi on parle, d'autres personnes qui ont un peu plus l'habitude le feront. Dis-toi que ce projet sert à faire en sorte que tout le monde sache ce qu'est un modèle et comment l'utiliser facilement.

--Misdre 10 mai 2011 à 05:52 (UTC)

Compris

Une mini-page d'aide concernant la documentation des modèles existe déjà ici >> Poképédia:Documentation des modèles. Elle est directement reliée au bandeau {{documentation}}, et même si elle est plutôt courte, il me semble qu'elle est assez claire dans l'ensemble. Si vous voulez la retaper, ne vous gênez pas.
Concernant le bot de surveillance, l'idée n'est pas mauvaise, mais comment un robot saura-t-il faire la différence entre une refonte purement esthétique d'un modèle et une autre mettant la moitié des anciens paramètres à la poubelle ? L'une peut-être beaucoup plus grosse que l'autre et n'avoir pourtant que des répercussions minimes ou inexistantes. (Cette question a été posée par un gros n00b n'ayant jamais compris par quelle magie ésotérique un bot peut bien fonctionner.)
-- Ίηνō¢Ќ ^{( -Kẅαάκ ?- )} 6 mai 2011 à 17:42 (UTC)

J'ai pas encore précisément réfléchi à la question, mais le fonctionnement du bot sera sans doute très simple : il vérifiera que dans la sous-page de documentation du modèle, on retrouve mention de tous les paramètres déclarés dans la page du modèle (tous les trucs commencant par {{{. Si ce n'est pas le cas, c'est que la documentation est incomplète/pas à jour.

Le bot serait lancé périodiquement (une fois par jour, quelque chose comme ça), fait les vérifications sur tous les modèles, et se rendort 24h. C'est assez simple dans l'idée, comme tu peux voir... le souci c'est le chemin inverse : comment le bot peut savoir qu'il y a des paramètres documentés qui n'existent pas dans le modèle ? Là, c'est plus dur, car on n'a pas {{{ avant chaque paramètre dans la page de documentation, donc c'est un peu hasardeux. Mais si déjà on avait la première vérif dont je parle deux lignes plus haut, ce serait pas mal.

--Misdre 6 mai 2011 à 21:22 (UTC)

Exemple de documentation aux normes

J'ai commencé à mettre aux potentielles futures normes la documentation du modèle Infobox Objet. Elle ne correspond plus tout à fait au modèle (noms des arguments) et c'est voulu mais j'y reviendrai ailleurs. On retrouve ce découpage :

1. Contexte
2. Utilisation : syntaxe et paramètres
3. Exemples
4. Voir aussi

On peut aussi noter la présence d'un bandeau de renvoi vers une page d'aide concernant les modèles.

Le contenu est perfectible, j'attends ici vos remarques et suggestions, pour réussir à se mettre d'accord sur une forme commune.
--Misdre 7 mai 2011 à 23:46 (UTC)

Je vais faire trois exemples :

• Un premier sur un modèle très court, sans paramètre : {{!}}
• Un second sur un modèle classique : {{Infobox Objet}}
• Un dernier sur un modèle imbriqué : {{TableauEvolutionHaut}}

J'ai bien avancé les deux premiers.
--Misdre 10 mai 2011 à 14:14 (UTC)

Trois considérations pour le moment :

1. À mon avis, les avertissements devraient être placés en haut de page. Ce sont les premières bannières sur lesquelles un utilisateur posera les yeux, ce qui dissuadera d'autant plus à la modification d'un modèle important.
2. Ensuite, je pense qu'il faudrait séparer « Syntaxe » dans le tableau de la doc de l'infobox objet, pour en faire une section spécifique. Le tableau serait moins lourd et l'ensemble beaucoup plus lisible.
3. Enfin, j'aime beaucoup les icônes que tu as placées. Elles permettent la mise en place d'une charte visuelle simple, ce qui s'avèrera utile pour ceux qui ont l'habitude de se frotter aux modèles et qui voudront la "survoler" rapidement et voir d'un coup d'oeil ce qui relève du sémantique, de la catégorisation auto et du facultatif. Par contre je pense qu'il y aurait peut-être une autre manière de les mettre en place.

Je vais mettre à jour la doc de l'Infobox Attaque pour présenter une alternative, qui ira globalement dans la direction que tu proposes.

-- Ίηνō¢Ќ ^{( -Kẅαάκ ?- )} 10 mai 2011 à 22:16 (UTC)

La mise à jour a été faite.

J'ai pris le parti de conserver la présentation des paramètres par liste et par sections plutôt que par un tableau, qui aurait été à la fois trop long et trop lourd à lire en raison du très grand nombres d'informations contenues par la page.

En ce qui concerne les icônes, j'ai finalement suivi ta méthode, en ajoutant tout de même un cadre de légende pour les expliquer en début de section.

-- Ίηνō¢Ќ ^{( -Kẅαάκ ?- )} 10 mai 2011 à 23:30 (UTC)

Je n'ai pas fini car je me prépare à aller en examen, mais j'ai modifié l'Infobox Objet pour prendre en compte certaines de tes remarques. En particulier, j'ai mis les bandeaux d'avertissement en haut de page, je ne l'avais pas fait au début parce que je ne pensais pas en faire des bandeaux, mais maintenant c'est plus logique/cohérent. J'ai aussi séparé la partie Syntaxe du tableau, moi aussi ça me semblait lourd.

J'ai récupéré ta légende des icônes, et j'ai aussi créé un modèle pour gérer les paramètres et les icônes associées. C'est encore tout chaud, mais ça facilite un peu l'insertion de ces informations.

Je réfléchis pour la mise en forme : tableau, liste, liste de définition (; :) ? je penche vraiment pour le tableau, j'aime pas trop la gueule que ça a mais il me semble qu'en changeant le style (pour le rendre plus proche du style des tableaux qu'on fait en ce moment, plus clairs) on aurait quelque chose de très bien.

--Misdre 11 mai 2011 à 10:37 (UTC)

Commenter ou ne pas commenter, telle est la question

Je pense que sur certains gros modèles, pas toujours clairs, il va falloir aller vers des commentaires dans le code. De là à le systématiser ? Dans quelles conditions et sur quels modèles ? En théorie, un modèle bien documenté devrait être suffisamment clair pour être compréhensible, pour qu'une tierce personne n'ayant pas codé le modèle puisse le modifier en comprenant à peu près.

Quand commenter ? Peut être lors de certains if à rallonge, certaines expressions mathématiques pas toujours évidentes ? Enfin je sais pas, c'est un peu pas très réfléchi, je pense juste que ça mérite d'être discuté. Je suis pas clair, mais j'espère que vous me comprenez !

Zhu' 10 mai 2011 à 19:24 (UTC)

A partir du moment où on a 2 niveaux de if, alors il faut commenter, pour moi. Si je n'avais pas commenté le modèle Galerie de sprites génération 5, je pense qu'il serait incompréhensible, d'autant que l'aération (absente de certains modèles comme les infoboxes) empêche de voir le début et la fin de chaque if. GreyDragon (Question ?) 10 mai 2011 à 19:45 (UTC)

OK, mais dans ce cas là il faudrait avoir un modèle exemple où c'est bien commenté, et il sera suivi pour tous les autres modèles concernés.

--Misdre 29 mai 2011 à 20:13 (UTC)

Bandeaux d'avertissement

J'ai créé quelques bandeaux d'avertissement à l'usage des modèles : Modèle protégé, Modèle avec données sémantiques, Modèle avec ParserFunctions, Modèle très utilisé. Ils sont encore bruts.

À terme le texte devrait être un peu plus fourni : je songe à avoir une première ligne en gras (sans doute le texte actuel des modèles) et, au-dessous, une ou deux lignes normales pour expliquer/donner plus d'informations (sans faire trop long, ça reste des bandeaux).

Si vous avez des icônes qui vous semblent plus adaptées, n'hésitez pas à les proposer également.
--Misdre 11 mai 2011 à 10:42 (UTC)

J'ai pensé que peut-être tous ces bandeaux pourraient être regroupés dans un seul modèle ?

-- Ίηνō¢Ќ ^{( -Kẅαάκ ?- )} 12 mai 2011 à 12:02 (UTC)

Un peu réticent à l'idée au début mais au final c'est sans doute mieux.

--Misdre 15 mai 2011 à 10:28 (UTC)