Utilisateur:Assassas77/brouillon aide documentation
Généralités modifier
Pour permettre un allègement des serveurs, une protection des modèles, la documentation des modèles sera séparée du code du modèle lui-même.
Chaque modèle documenté devrait être lié à sa page de documentation ainsi :
- Le nom de la page du modèle est formé de «
Modèle:» suivi du nom du modèle. - Le nom de la page de documentation est composé du nom du modèle suffixé par
/documentation(la barre oblique est nécessaire et représente une sous-page). Cette page placera la documentation sur un fond vert clair. Ainsi les exemples seront très facilement réaliser pour leur mise point.- Exemple pour le modèle
{{Alinéa}}:Modèle:Alinéa et Modèle:Alinéa/documentation.
- Exemple pour le modèle
Le contenu de la page de modèle:
- pourra commencer par
<includeonly>(sans aucun saut de ligne de part et d'autre) et se finir par</includeonly>(sans aucun saut de ligne de part et d'autre), s'il n'est pas possible d'en faire une visualisation immédiate sans erreurs générées, du fait de l'absence de certains paramètres (mais c'est déconseillé, on devrait toujours pouvoir afficher la page du modèle sans erreur, ce qui permet ensuite en cas de modifications ultérieure de prévisualiser immédiatement les modifications sans avoir d'abord à modifier la documentation) ; - devra ensuite être suivie immédiatement de
<noinclude>{{Documentation}}</noinclude>
La catégorisation d'un modèle se fera non pas dans le modèle principal mais dans sa sous-page "/Documentation" (à l'emplacement mentionné par le modèle affiché qui invite à créer cette documentation), uniquement à la fin de cette sous-page entre les balises <includeonly> et </includeonly> (là il est possible d'utiliser des sauts de ligne entre les catégories mentionnées). Ainsi placées, ces catégories indiquées pour le modèle principal n'auront aucun effet pour la sous-page de documentation elle-même.
Si on veut catégoriser une sous-page de documentation (par exemple pour des problèmes de rendu des tests ou exemples inclus ou d'autres tâches restant à y effectuer), il faut le faire dans ces sous-pages entre les balises <noinclude> et </noinclude>. Ainsi placées, ces catégories indiquées pour la sous-page n'aura aucun effet sur la catégorisation du modèle principal.
Structure modifier
Quant au contenu de la documentation, la structure interne de la documentation commence à se généraliser par mes soins pour permettre une lisibilité homogène sous la forme suivante :
- Raccourci éventuel du modèle :
{{Raccourci|<nowiki>{{modèle}}</nowiki>|nolien=1}}oùmodèlereprésente le raccourci. - Description : décrit les actions et les utilisations du modèle en omettant le plus souvent possible le codage wiki ou HTML.
- Il sera ajouté au fur et à mesure les balises
<section begin=description /><section end=description />qui permettront de récupérer le texte de cette rubrique de description en vue d’un affichage globale avec tous les autres modèles (voir l'ébauche de la Liste des modèles (en chantier). Ce qui permettra d'avoir une documentation toujours à jour concernant le résumé du descriptif d'un modèle. Cf.{{descriptif}}.
- Il sera ajouté au fur et à mesure les balises
- Syntaxe(s) : affiche les accolades et le contenu du modèle. Décrit les arguments (le terme paramètre a été retiré, n’étant pas spécifique à l’informatique au contraire d’argument) nécessaires et leurs fonctions. Le caractère obligatoire ou non de la fonction (termes en petites capitales : obligatoire ou optionnel).
- Sa syntaxe sera «
:{{le-modèle|argument-un|argument-deux…}}</code> »suivi au dessous de Arguments : et leur description listés par des puces bleues. Chaque argument, chaque valeur sera encadré de la fonction HTML<code></code>. La valeur par défaut et les unités utilisées seront présentes si c’est pertinent.
- Exemple(s) : affiche entre deux balises
<pre></pre>le contenu qui sera affiché au-dessous.
- On démarrera généralement avec une mise en page sur le côté gauche à l’aide des balises
<div class="pagetext"></div>qui encadreront tous les exemples.
- Voir aussi : liste de liens ou de modèles (listés sous forme de puces bleues) qui pourraient s’avérer utile.
- puis la liste des catégories :
<noinclude>[[Catégorie:Documentations]]</noinclude><includeonly>[[Catégorie:une catégorie]][[Catégorie:Modèles documentés]]</includeonly>
Remarque : Lorsque la documentation est très longue, on pourra remplacer le point-virgule au profit du signe égal pour présenter les rubriques.
Remarques modifier
- À la fin de la documentation, entre les balises
<includeonly></includeonly>(où se trouvent déjà les catégories francophones), on essaiera de mettre les Templates (modèles) étrangers ! ([[en:Template:a-template]]) en n’en plaçant qu’un par ligne. - Parfois, il y aura une rubrique Remarque(s) ou une autre clairement affichée.
- Lorsqu’aucune documentation n’est réalisée, il faudra impérativement placer dans la documentation le modèle
{{sansdoc}}. - On prendra soin d’espacer ces rubriques par trois retours de paragraphe, permettant ainsi de rendre la documentation plus aérée. Pour faire une petite marge, chaque paragraphe en romain (en non gras) commencera par un deux-points.