Toute personne peut participer. Les pré-requis sont réduit à l’essentiel :
- avoir un compte sur spip.net
- connaitre une balise, un critère, ... non documenté et connaitre un cas d’utilisation associé.
- avoir lu cet article pour comprendre les quelques spécificités liées à la documentation
Titrer l’article
- un filtre :
|nom_du_filtre - une balise :
#NOM_DE_LA_BALISE - un critère :
{nom_du_critère}
Résumer l’élément documenté
Le chapeau sert à introduire le concept présenté :
- une ou deux phrases de résumé du texte ou de présentation de l’élément. Ce texte est utilisé par les modeles
<critereXX>,<baliseXX>(exemple de cas d’utilisation La boucle ARTICLES)
Décrire le concept
Le champ Texte sert à la description exhaustive (autant que possible) de l’élément documenté :
- une majuscule en début de phrase
- encadrer par les tags <code> et </code> le nom de l’élément (exemple : « la balise
#BALISE... »), les urls de l’espace privé (exemple : « en allant sur?exec=config_fonctions... »), parfois le résultat affiché (exemple : « la date retournée sera du type1970-01-01 00:00:00») - privilégier les tags (plus lisibles) <code> et </code> à <cadre> et </cadre>
- hiérarchiser son texte (intertitres, paragraphes)
- Globalement
- s’en tenir à documenter le seul élément dont il est question (ne pas vouloir tout dire, éviter les digressions, les trucs et astuces, ...)
- vérifier a minima (en lisant le code) les informations fournies
Utiliser les mots clefs
- Indiquer la version de spip ayant introduit l’élément documenté. Pour cela utiliser l’écriture :
(depuis [{}->artxxxx])où « xxxx » est l’id de l’article présentant la version de SPIP et où les{}permettent, si nécessaire, un renvoi automatique sur la traduction de l’article, facilitant ainsi le travail des traducteurs (voir : Les auto-références multilingues de la documentation). - Pour les balises
- Indiquer si c’est une balise « statique » (issue de la base de donnée) ou bien « dynamique » (calculée, traitée par une fonction)
- indiquer si nécessaire (pour une balise par exemple) le type de boucle concernée
- faire au mieux :)
... à suivre