Qualsevol persona pot participar. Els requisits previs es redueixen a l’essencial:
- tenir un compte a spip.net
- conèixer una etiqueta, un criteri, ... no documentat i conèixer un cas d’ús associat.
- haver llegit aquest article per comprendre algunes especificitats lligades a la documentació
Posar un títol a l’article
- un filtre:
|nom_du_filtre - una etiqueta:
#NOM_DE_LA_BALISE - un criteri:
{nom_du_critère}
Resumir l’element documentat
L’encapçalament serveix per introduir el concepte que presentem:
- una o dues frases de resum del text o de presentació de l’element. Aquest text s’utilitza pels models
<critereXX>,<baliseXX>(exemple de cas d’ús El bucle ARTICLES)
Descriure el concepte
El camp Text serveix per descriure de manera exhaustiva (tant com sigui possible) de l’element documentat:
- majúscula a l’inici de la frase
- emmarcar amb els tags <code> i </code> el nom de l’element (exemple: «l’etiqueta
#BALISE...»), els urls de l’espai privat (exemple: «anant a?exec=config_fonctions...»), a vegades el resultat mostrat (exemple: «la data retornada serà del tipus1970-01-01 00:00:00») - afavorir els tags (més llegibles) <code> i </code> respecte a <cadre> i </cadre>
- jerarquitzar el seu text (subtítols, paràgrafs)
- Globalment
- limitar-se a documentar l’element al que es fa referència (no voler dir-ho tot, evitar les digressions, els trucs i astúcies, ...)
- verificar al mínim (llegint el codi) les informacions proporcionades
Utilitzar les paraules clau
- Indicar la versió d’SPIP que ha introduït l’element documentat. Per fer-ho, utilitzar l’escriptura:
(a partir de [{}->artxxxx])on «xxxx» és l’id de l’article que presenta la versió d’SPIP i on els{}permeten, si és necessari, un reenviament automàtic cap a la traducció de l’article, facilitant d’aquesta manera el treball dels traductors (veure: Les auto-referències multilingües de la documentació). - Per les etiquetes
- Indicar si és una etiqueta «estàtica» (sortida de la base de dades) o bé «dinàmica» (calculada, tractada per una funció)
- indicar, si és necessari (per mitjà d’una etiqueta, per exemple) el tipus de bucle al que es refereix
- fer-ho el millor possible
:-)
... continuarà