Participar en la documentació d’etiquetes, criteris, filtres d’SPIP

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 tipus 1970-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à

Autor merce Publié le : Mis à jour : 26/10/12

Traductions : català, English, français, Nederlands