Guide de rédaction pour SPIP-Contrib

A. Savoir de quoi on parle

Savoir de quoi on parle, ça semble vraiment évident quand on commence à écrire un article.

Pour cela,
-  Le titre de l’article doit annoncer le sujet principal de l’article et si possible préciser son approche.
-  Le chapeau, ou la première partie de l’article si il n’y a pas de chapeau, doivent impérativement permettre de savoir ce qu’on va trouver d’utile dans cet article.

Mais savoir de quoi on parle, c’est aussi savoir de quoi on ne parle pas. Chaque sujet abordé mais “hors sujet” serait une distraction par rapport à l’objet de l’article, et induit donc une perte de pertinence et une perte d’efficacité à cette documentation.

En conséquence :
-  Savoir de quoi on parle dans un article donné implique de pas aborder 1001 autres sujets différents dans cet article, ni même 10 : juste parler de ce dont on a choisi de parler dans cet article.
-  Il en va de même pour chaque partie : chaque intertitre doit annoncer le contenu de la partie suivante, qui ne doit aborder que ce sujet là.
-  Enfin, chaque paragraphe et chaque phrase doivent s’intégrer dans une progression logique et ne pas digresser.

B. Spip-contrib est un site documentaire autour de SPIP

Il y a donc une dimension informatique, pédagogique, explicative, documentaire.

Les informations diffusées doivent être exposées progressivement.

Chaque article s’adresse à un public donné. Il n’est en général pas possible de s’adresser à tous les publics : un certain prérequis est nécessaire. Selon les articles, ce prérequis peut être basique ou très évolué, dans différents domaines (connaissance du web, création basique ou avancée de squelettes, connaissance de MYSQL, de PHP, de javascript...). Une fois le choix de ce public fait, il faut s’y tenir.

L’auteur d’un article ne maîtrisant parfois qu’imparfaitement le sujet dont il parle, il est important de faire la part des choses entre 1) ce qui est certain 2) ce qui est incertain.

-  Un article dans spip-contrib doit être “suffisamment” complet et exact sur le sujet abordé.
-  Les informations dans un article doivent être certaines.

Les informations incertaines ou incomplètes peuvent éventuellement alimenter un article du Carnet, le temps d’être complétées, validées et mises en forme.

Le vocabulaire employé doit être adéquat au domaine considéré.

C. Spip-contrib n’est pas un blog sentimental

Spip-contrib n’est pas un blog sentimental, et donc il ne faut pas y mélanger les avis personnels sur les membres de l’équipe spip, ou sur des discussions ayant eu lieu sur IRC.

Il ne faut pas non plus arroser le texte d’impressions personnelles, de ressentiment à l’égard de certains aspects de SPIP ou des SPIPeurs : juste expliquer, présenter, documenter.

Autrement dit :

1. ne pas mêler la vie des spipeurs ou d’IRC avec les documentations ou explications pédagogiques.
2. ne pas mêler des sentiments personnels avec les documentations ou explications pédagogiques

D. Spip-contrib n’est pas un blog artistique ou littéraire

Les maniérismes littéraires nuisent en général à la fonction de spip-contrib qui est de transmettre le mieux possible un contenu pratique ou technique.

Quant aux private jokes, elles présentent certes un intérêt pour 3 ou 9 personnes, mais qu’en est-il pour les 20000 autres utilisateurs de SPIP qui s’en sentiront exclus ?

E. N’abusez pas des notes de bas de page

Le Post Scriptum, les notes de bas de page et les remarques sont des manières d’introduire des précisions ou des digressions, mais elles doivent toujours uniquement servir l’objet principal de l’article.

Leur abus rend la lecture difficile et ne permet plus de distinguer l’essentiel de l’accessoire, ces abus sont donc à proscrire. Trop de notes tuent la note.

Donc avant de créer une note de bas de page, posez vous les questions suivantes :
-  est-ce que cette note est importante pour le sujet principal de l’article ?

1. si oui, ce contenu doit aller dans le texte principal lui-même, pas dans une note.
2. si non, pourquoi le mettre dans cet article particulièrement ? Peut être faut il mieux ne pas la mettre, et privilégier la clarté de l’exposé principal.

Il y a plusieurs alternatives aux notes de bas de page :
-  rassembler toutes les notes en relation avec le sujet dans une même partie, en fin d’article comme une annexe, une FAQ par exemple, ou une partie “Autour de ce sujet”.
-  créer un article dans le carnet dans contrib ou avec tous les compléments d’informations annexes
-  créer un article qui développe le sujet d’une note particulière, si elle le mérite.

F. Enrichissements typographiques

Par enrichissement typographique, on entend les décorations du texte :
-  gras
-  italique
-  MISE EN MAJUSCULE
-  balises SPIP prédéfinies <quote> et <poesie>
-  texte de couleur, textes big
-  TOUTES les combinaisons possibles de ces enrichissements

Les enrichissements typographiques doivent être utilisés à bon escient, et en quantité limitées.

Si possible, chacun des enrichissement doit être associé à une sémantique, facilement repérable intuitivement par le lecteur : l’insistance, la citation, l’exemple, etc. Chaque sémantique doit toujours se traduire par le même enrichissement.

Par exemple, pour attirer l’attention sur des termes spécifiques, n’utilisez pas tour à tour le gras, puis le rouge, puis les majuscules, mais choisissez : par exemple, les doubles accolades SPIP, qui se traduisent par un strong, c’est-à-dire un gras sur spip-contrib.

En général, il ne faut pas utiliser plus d’une ou 2 formes seulement d’enrichissement typographique dans un article, ou 3 éventuellement. En utiliser plus risque de rendre la page difficilement lisible (le syndrôme “arbre de Noël” ou “gif animé”).

G. Conventions typographiques

Comme vu précédemment, les possibilités d’enrichissements typographiques sont nombreuses, cependant certaines conventions et usages régissent la rédaction d’articles dans la galaxie SPIP afin d’uniformiser et de faciliter la lecture.

Pour désigner un morceau de code (balises, filtres, fichier php) utilisez les backticks ` pour encadrer le morceau. Comme par exemple mes_options.php (`mes_options.php`)

Il en va de même pour indiquer une arborescence : squelettes/css/ pour indiquer le chemin où mettre le fichier perso.css

Pour indiquer une suite de clics à réaliser pour naviguer dans l’interface graphique, utilisez les guillements " pour encadrer la navigation et les chevrons fermants > pour préciser la succession de boutons, tout cela en gras. Par exemple pour indiquer comment changer le nom du site : “Configuration > Identité du site”