Utilisateur:Koreller/Documentation/Modèles

La bibliothèque libre.

Cette page présente ma démarche de refonte de la documentation des modèles sur Wikisource.

Point de départ[modifier]

La documentation des modèles m'a tenté après avoir compris comment manipuler le wikicode. J'ai réussi à être à l'aise avec le wikicode après un certain temps à contribuer sur Wikipédia (je m'y suis inscrit en avril 2015), et notamment avec mes refontes graphiques des portails de Wikipédia et du Wiktionnaire.

Constat et démarche[modifier]

J'ai été usager de la documentation des modèles de Wikisource et j'y ai vu les soucis que j'y vivait en temps que contributeur. Je me suis donc décidé à modifier cela.

Pour la documentation des modèles de Wikisource, je pense qu'il faut que l'utilisateur soit à l'aise avec la structure, qu'il puisse identifier rapidement l'information qu'il recherche, et qu'il ai facilement des exemples (s'il veux utiliser encore plus rapidement le modèle).

J'ai trouvé que les modèles de Wikisource (du moins les plus utilisés) méritaient d'avoir une structure plus organisé et plus reconnaissable. En effet, ceux-ci ne suivaient pas de structure particulière, les noms des sections étaient souvent différentes, les exemples formatés de différentes façons, et pas toujours clair. Par exemple, l'adoption du modèle {{Code rendu}} m'a beaucoup aidé au formatage des exemples.

J'ai fais des changements unilatéraux pour harmoniser un grand nombre de modèles, c'est à dire que je n'ai pas demandé à la communauté avant de faire des changements pour mettre en place un squelette commun aux documentation des modèles. Je pense que si c'était à refaire je laisserai un message à la communauté sur le Scriptorium, mais j'ai eut de la chance et je n'ai jamais eux aucune remarques négative (de revert, de sujet en PDD, etc.).

Pour la refonte des modèles je suis toujours parti de la documentation préexistante (sauf pour de rare cas où le modèle est très simple à comprendre) et pour sélectionner les modèles j'ai pris ceux que j'utilisais souvent, puis je suis aller voir sur les pages Aide:Liste des modèles et Aide:Liste des modèles (en chantier).

Code communs aux modèles[modifier]

Pour la refonte de la documentation des modèles sur Wikisource, je suis parti de la structure de wikicode suivante : 

__NOTOC__
== Utilisation ==

=== Remarques ===

== Syntaxe ==
<code><nowiki></nowiki></code>

=== Syntaxe simplifiée ===
<code><nowiki></nowiki></code>

=== Syntaxe complète ===
<code><nowiki></nowiki></code>

== Paramètres ==

== Exemple ==
{{Code rendu}}
|-
| <pre><nowiki>{{en}}</nowiki></pre> || <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em">{{en}}</div>
|}

{{Code rendu}}
|-
| <pre><nowiki>{{en}}</nowiki></pre> || <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em">{{en}}</div>
|}

== Voir aussi ==
* {{m|}}

Autre bout de code 

<div class="pagetext" style="margin:0.5em 0;margin-left:2em;background:#FFF;color:#000;border:1px solid #AAA;padding:2px .5em">
</div>
<includeonly>[[:Catégorie:]]</includeonly>
<noinclude>[[Catégorie:Documentations]]</noinclude>

J'ai essayer de faire rentrer dans ce cadre tous les modèles que j'ai refondu (ou la plupart).

Section « Utilisation » et sous-section « Remarques »[modifier]

Pour le formatage de la section « Utilisation » j'ai essayé de mettre en avant sa fonction première : « à quoi sert le modèle » (pour que l'utilisateur identifie s'il doit l'utiliser pour son problème).

Je commence systématiquement cette section par : « Permet de… ». Peut-être qu'il faudrait que j'enlève ses deux petits mots, car si sans ces deux mots la phrase est clair, il n'y a pas de raison pour qu'ils y restent.

La sous-section « Remarques » est quand à elle plus rare, elle me sert à pour décrire des modèles avec plusieurs fonctions, je m'appuie sur la documentation préexistante et je fais une mise en forme en liste à puce (exemple : {{Lang}}, {{Modernisation}}). Toujours dans l'objectif de clarté et de simplicité. Cette sous-section existe aussi parce que lorsque je trouve beaucoup d'informations sur la documentation préexistante et que je ne sais pas dans quelle section cela serait pertinent de les y faire figurer, je les y insère.

Section « Syntaxe »[modifier]

La section « Syntaxe » sert à afficher un code facilement copiable.

La plupart du temps, la section syntaxe n'a pas de sous-sections, le code complet du modèle étant souvent simple, il ne nécessite pas de découpage particulier.

Pour des modèles n'utilisant pas toujours tous les paramètres, je trouve pertinent de proposer deux sous-sections « Syntaxe simplifiée » et « Syntaxe complète ».

  • la première « Syntaxe simplifiée » servant d'utilisation de base du modèle (souvent 2-3 paramètres)
  • la seconde « Syntaxe complète » servant à proposer tous les paramètres (de manière exhaustive)

Je pense que dans certains cas — si un utilisateur utilise beaucoup le modèle duquel il rajoute 1-2 paramètres, ou pour deux usages distincts mais récurrents — il serait pertinent de créer plusieurs syntaxes simplifiées, mais il faut veiller à ne pas perdre le primo utilisateur du modèle (et de sa documentation).

Section « Paramètre »[modifier]

La section « Paramètre » est l'occasion pour moi d'insérer le modèle TemplateData sur la documentation, il y a plusieurs avantages à cela :

  • Les arguments sont clairement identifiés ; exemple : {{centré}} le paramètre « 1 » signifie « Texte à centrer » ce qui n'était pas forcement visible aussi clairement dans la documentation précédente
  • Les arguments sont exhaustifs ; en effet, lors de la création du TemplateData cela force à devoir comprendre tous les paramètres, s'ils tout étaient documentés pas de souci, mais si certains ne l'était pas il faut essayer de documenter l'usage du paramètre qui n'avait pas été décrit. Cela permet de clarifier les alias de certains paramètres

Par ailleurs, je mets le TemplateData même s'il n'y a pas de paramètre, dans le but de signaler qu'il n'y a pas de paramètre (exemple : {{Titre sous-page}}).

Ce qui est compliqué dans le TemplateData, c'est pour le cas où un paramètre s'utilise comme cela : {{séparateur|l}} ({{séparateur}}) : c'est à dire sans valeur au paramètre. Pour le décrire je suis embêté car je n'ai pas trouvé de solution uniforme, j'espère que la section des exemples permet de palier à cette lacune et d'en comprendre l'utilisation.

Section « Exemple »[modifier]

Pour la section « Exemple », l'objectif est :

  • de montrer ce que fais visuellement le modèle
  • comment il fonctionne
  • montrer le rendu
  • permettre de commenter un cas complexe en contexte

Pour la section exemple, Assassas77 à bien travaillé pour me permettre d'utiliser le modèle {{Code rendu}}. Ce modèle me permet de facilement présenter le code à gauche et son résultat à droite.

Parmi le résultat à droite, j'utilise parfois l'argument <div class="pagetext" style="margin:0.5em 0; margin-left:2em; background:#FFF; color:#000; border:1px solid #AAA; padding:2px .5em"> pour montrer comment réagit le modèle dans l'espace « Page: », et pour montrer les effets de marges (exemple: {{séparateur}}). Ne pas utiliser la class pagetext est pertinent lorsque le modèle ne s'utilise pas dans l'espace page ou s'il ne réagit pas différemment (exemple : {{ChapitreNav}}, {{1o}}).

Section « Voir aussi »[modifier]

La section voir aussi présente les modèles susceptibles d'intéresser le contributeur, ou même de l'aider à trouver le modèle qui répond le mieux à son besoin.

Modèles[modifier]

Quelques modèles intéressant car complexe ou présentant une particularité :

Reste à faire[modifier]

Liste de modèles : Aide:Liste des modèles et Aide:Liste des modèles (en chantier), (Spécial:Modèles les plus liés) et ceux dont je voudrais réorganiser la documentation :

Réalisation[modifier]

Sur Wikisource, j'ai fais de nombreuses refontes de documentation des modèles entre fin décembre 2020 et mi-février 2021 (1 mois et demi). J'ai fais la refonte de la documentation des modèles suivants :

Récupérée de « https://fr.wikisource.org/w/index.php?title=Utilisateur:Koreller/Documentation/Modèles&oldid=13367400 »