Aller au menu - Aller au contenu

[Validation] Les conseils des Validateurs

Informations sur le tutoriel

Avatar
Auteur : Thunderseb
Visualisations : 27 209


Plus d'informations Plus d'informations
Logo Validateur
Dans ce mini-tuto (qui fait office d'article), nous (toute l'équipe des Validateurs) avons décidé de vous donner quelques conseils pour passer avec brio la validation de votre tutoriel. :)
Sommaire du tutoriel :
Icône du chapitre

Le choix du sujet

Un tutoriel a pour but d'expliquer quelque chose. Qui dit expliquer dit également apprendre. Un tutoriel sert donc à apprendre aux lecteurs à faire quelque chose. Ce quelque chose peut aller du maniement de l'outil Plume de Photoshop à la réalisation d'un BBCode Javascript en passant par la création d'un flux RSS avec PHP, sans oublier le placement d'une mitrailleuse fixe dans Half-Life².

Thunderseb
Bref, il peut y avoir des tutoriels dans tous les domaines. Cette définition du tutoriel est très importante ! En effet, il existe ce que l'on appelle des TEA (Trucs Et Astuces). Ces TEA ne sont pas des tutoriels, même s'ils y ressemblent. Ils n'ont pas pour but d'apprendre quelque chose à l'utilisateur. Par exemple, le classique TEA est « Comment faire un texte de feu ». Il y a juste une marche à suivre, et c'est tout. Ce TEA ne permettra à l'utilisateur que de faire des textes de feu, et rien de plus. Tandis qu'un tutoriel sur l'utilisation de l'outil Plume se révélera plus utile ; lors de détourages ou de créations de formes par exemple.

Pour résumer, il faut bien faire la distinction entre montrer quelque chose et expliquer quelque chose. Un TEA a pour unique fonction de montrer quelque chose au lecteur, et nous n'acceptons pas ce type de propositions.


N'abordez pas des choses trop simples non plus. Ça ne sert à rien d'expliquer les structures conditionnelles de PHP alors que le big-tuto de M@téo le fait, soyez logique.

La rédaction

Il faut bien vous dire que le tutoriel sera rédigé en français. Eh oui, et même rédigé dans un français relativement acceptable, c'est-à-dire sans fautes d'orthographe. Cela veut donc dire que le langage SMS, ou plutôt MSN, est totalement déprécié et votre tutoriel, s'il est rédigé en ce "langage", n'aura pas la moindre chance d'être accepté même en donnant 200 euros à chaque validateur.

Vous devez donc avoir une bonne orthographe, et si ce n'est pas le cas, faites-vous relire par une personne compétente en la matière.


Relisez-vous à haute voix pour vérifier si vos phrases ne sont pas boiteuses, car quand on écrit, on pense parfois à autre chose et on oublie des mots, ou on en écrit de trop. Cela servira aussi à déceler les phrases difficilement compréhensibles ou trop longues.

Ce dernier point m'amène donc à vous parler de la ponctuation :)

Les virgules, c'est important ; une phrase longue sans virgules est difficilement compréhensible. Par ailleurs, je me permets de vous rappeler quelques conventions d'écriture de la ponctuation :

Nom Symbole Avant Après
Virgule , Pas d'espace Espace
Point . Pas d'espace Espace
Point-virgule ; Espace Espace
Point d'exclamation ! Espace Espace
Point d'interrogation ? Espace Espace
Deux-points : Espace Espace
Tiret - Espace Espace
Trait d'union - Pas d'espace Pas d'espace
Parenthèse ouvrante ( Espace Pas d'espace
Parenthèse fermante ) Pas d'espace Espace (sauf devant un point ou une virgule)
Apostrophe ' Pas d'espace Pas d'espace
Guillemet typographique ouvrant « Espace Espace
Guillemet typographique fermant » Espace Espace
Guillemet droit ouvrant " Espace Pas d'espace
Guillemet droit fermant " Pas d'espace Espace


Le type de guillemet dépend évidemment du logiciel avec lequel vous tapez votre texte. Word mettra certainement des guillemets typographiques, alors que le bloc-notes en mettra des droits (normal, puisqu'on s'en sert pour écrire du code).

En parlant de Word, prenez l'habitude de rédiger vos tutos avec un éditeur de texte conçu pour ça, comme Word, ou encore Writer de OpenOffice.org. Il vous corrigera déjà les fautes de frappe, les accents, et la ponctuation (en référence à la table ci-dessus).

La mise en forme

Un tutoriel doit être bien présenté. Nous refusons fréquemment des tutoriels à cause de leur présentation négligée. Voici quelques conseils de présentation.

Reportez-vous à la doc du ZCode, ici


Les images



Si vous mettez des images dans votre tutoriel, essayez de les centrer ! Ça prend un clic de souris avec la zForm, VTO ou FoxyCode (extension ZCode pour Firefox).

Prenez également l'habitude de passer une ligne avant et après l'image, pour ne pas qu'elle soit collée au texte.

N'hésitez pas non plus à utiliser les flottants pour disposer vos images, ça peut être d'un bel effet.

Code : Zcode
1
<flottant valeur="gauche"><image>img.gif</image></flottant>Patati patata [...]


Si vos images sont très larges ou même très hautes, utilisez les miniatures, c'est plus présentable, et moins long à charger, dans le cas d'un tuto très long ;)

Le texte



C'est un peu bête à dire, mais le texte, c'est moche. Evitez les gros blocs de texte de 20 lignes de long à la Lorem Ipsum. Ça risque de faire peur au lecteur ^^ Pensez à aérer votre texte (faire des paragraphes).

Evitez les couleurs flash, limitez vous à la couleur du texte brut. Vous pouvez bien sûr mettre un peu de rouge ou de bleu, mais évitez les autres couleurs, car tout le monde n'a pas forcément le même design que le vôtre.

Le Gras et l'Italique, en HTML ont été créés pour marquer l'emphase, pour mettre en évidence. C'est pareil dans un tuto (même si le code HTML produit n'est pas sémantique ^^ ). Quand vous parlez d'une fonction ou d'une variable PHP, d'un attribut HTML ou encore d'une entité HL², n'hésitez pas à mettre en gras, pour bien montrer au lecteur que ce n'est pas du texte normal.

Ne faites pas :



  • ['] ainsi element est appelée et insérera les balises dans le textarea contenu.


Faites :



  • ['] ainsi element est appelée et insérera les balises dans le textarea contenu.
Pour les titres, pensez aussi qu'il existe des balises justement conçues pour cela et qui permettent de mettre en forme vos chapitres et paragraphes :
Code : Zcode
1
<titre1/>
Ce qui donne :

exemple



Code : Zcode
1
<titre2/>
Ce qui donne :

exemple



Pour mettre un titre, ces balises sont obligatoires (ou du moins fortement conseillées). La présentation sera plus agréable avec que si vous utilisez des balises < gras >, < souligne >... à tout bout de champ, donc pensez-y :) .

Les blocs



Les blocs Information, Question, Erreur et Attention sont là pour alerter ou informer le lecteur. Si vous en abusez, ils perdent tout leur sens. Ne les utilisez que quand ils sont réellement utiles ;)

Les listes à puces



Le ZCode, comme le BBCode permet de créer facilement des listes à puces. Utilisez-les !

Il n'y a rien de plus laid qu'un texte à puces avec des tirets. Ça, ça fait vraiment négligé et ça nuit gravement à la présentation. Nous insistons sur ce point !

Code : Zcode
1
2
3
4
<liste>
<puce>Puce 1</puce>
<puce>Puce 2</puce>
</liste>


Les tableaux



Vous pouvez utiliser des tableaux pour structurer des listings, des listes d'attributs, des fonctions' Ils sont d'une utilisation assez facile, bien plus facile que les tableaux BBCode et Wiki. Dans tous les cas un tableau sera plus beau qu'une liste mal foutue ^^

Définitions et citations



Citation : Ma prof de français
Citez vos sources, nom d'un chien !


Si vous donnez une définition, mentionnez la provenance de celle-ci, au moyen d'un bloc de citation.

Vous pouvez aussi utiliser la balise très méconnue qu'est Wikipédia :

Code : Zcode
1
Pour plus d'informations : <lien type="wikipedia" url="ruby">voyez Ruby</lien>


Qui donne :

Pour plus d'informations : voyez Ruby

La présentation des codes

Si vous rédigez un tutoriel exposant des codes sources, il est important de bien présenter ces derniers. C'est très important car un code bien présenté, proprement indenté est un code facile à lire et à comprendre.

Les sources HTML et XHTML



Les codes HTML présentés dans les tutoriels doivent être valides et correspondre au doctype défini (dans le cas d'un code complet). Il est également important d'indenter proprement le code pour en faciliter la lecture.

A ne pas faire :



Code : HTML - A ne pas faire
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
<html>
<head>
<TITLE>Exemple de code</TITLE>
<script language="JavaScript" src="demo.js"></script>
</head>
<body>
<div ID="all">
<center>Texte centré</center>
<IFRAME src="demo.html" width="100%"></IFRAME><img align='right' src='demo.gif' />
</div>
</body>
</html>


Il n'y a pas de doctype, c'est un mélange de HTML et de XHTML avec des balises obsolètes (CENTER et IFRAME)... bref, c'est mauvais et ce genre de code est refusé !

Code propre accepté :



Code : HTML - Code propre
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xml:lang="fr" xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>Exemple de code</title>
<script type="text/javascript"src="demo.js"></script>
</head>
<body>
        <div id="all">
                <div class="center">Texte centré</div>
                <!-- IFRAME n'est pas valide -->
                <img src="demo.gif" alt="Attribut ALT obligatoire" />
        </div>
</body>
</html>


Le code est bien indenté, correspond bien au doctype, bref, ce code est acceptable :) .

Les codes source



Votre code doit être bien indenté, que ce soit du CSS, du Javascript, du C ou du Ruby. Dans tous les cas une présentation optimale garanti une lecture et une compréhension optimale. Vous pouvez bien sûr indenter le code comme vous le désirez (K&R, BSD/Allam...), du moment que ce soit lisible. Les codes compressés (Fonction javascript écrite sur une seule ligne pour alléger le fichier par exemple) sont bien sûr proscrits.

Code accepté



Code : PHP - Code accepté
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<?php
while($donnees = mysql_fetch_assoc($requete)) {
    if($donnees['id'] == 1) {
        echo 'Valide';
    }
    else {
        echo 'Non valide';
    }
}
?>


Vous pouvez aussi commenter vos codes. Mais attention, trop de commentaires tue les commentaires ! Si vous mettez des commentaires, mettez le strict nécessaire, sinon vos codes pourraient se retrouver noyés dans cette masse d'explications ;) .

Codes PHP



Les codes PHP doivent être soumis aux mêmes exigences que tous les codes (indentation, commentaires...). Il y a cependant quelques exigences supplémentaires :

Balises <?php ?>



Tous les codes PHP doivent être encadrés par des balises <?php et ?>, sinon le code PHP ne sera pas coloré !

or die(mysql_error()) à la fin de chaque requête



Il est important d'ajouter or die(mysql_error()) à la fin des requêtes de manière à détecter simplement les erreurs :

Code : PHP - or die(mysql_error())
1
2
3
<?php
$retour = mysql_query('SELECT * FROM news ORDER BY id') or die(mysql_error());
?>


Protection contre les injections SQL



Il faut aussi veiller à la sécurité des codes et notamment protéger les scripts contre les injections SQL.

Pour les données numériques :
Code : PHP - Données numériques
1
2
3
<?php
$page = intval($_GET['page']);
?>


Pour les données textuelles :
Code : PHP - Données textuelles
1
2
3
<?php 
$titre = mysql_real_escape_string($_POST['titre']) 
?>


Les portions de code "inline"



Il peut être intéressant de placer des portions de code au sein d'une phrase. C'est pour satisfaire cette demande que le balise MINICODE a été créée :

Code : Zcode
1
La boucle <minicode type="javascript">while (plop != "string")</minicode>. Elle est exécutée jusqu'à ce que <minicode>plop</minicode> valle <minicode>string</minicode>.


Ce qui donne :

La boucle while (plop != "string") est exécutée jusqu'à ce que plop valle string.

Les zUploads

Vous devez héberger vos images sur le Site du Zéro, c'est impératif. Comme ça, elles resteront toujours présentes au côté du tutoriel (si ce n'est pas mignon ça Image utilisateur )



Au secours, j'ai atteint mon quota, que faire ?


Je sais, c'est assez râlant ça :colere2:

N'oubliez pas que votre tuto est destiné au Web, et que sur un site Web, le .jpg est déprécié. Faites vos images et vos screenshots en .gif ou en .png indexé. Grâce à cela, vous gagnerez déjà un peu de place ;)

Pour ces 2 formats, vous pouvez également réduire le nombre de couleurs. N'oubliez pas que vous faites un tutoriel, pas une image .tiff en haute résolution. L'image doit être lisible, et si elle est légèrement pixellisée, ce n'est pas grave :)

Pour finir, avec les zUploads, pensez aux miniatures. Pour rappel, c'est le petit bouton Image utilisateur.

Ah oui, j'en profite pour vous dire que vous pouvez aussi utiliser l'attribut legende dans vos balises image. Son contenu remplacera le traditionnel « Image utilisateur » (l'attribut HTML alt).

Code : Zcode
1
<image legende="bannière SDZ">http://www.siteduzero.com/Templates/images/designs/19/logo_sdz_fr.png</image>

Les zCorrecteurs

Image utilisateur


Avant de nous soumettre votre tutorial, vous pouvez d'abord le soumettre aux zCorrecteurs.

C'est quoi ces zCorrecteurs ?


Image utilisateur
C'est une bande de fous ^^ de bénévoles, qui travaillent en collaboration avec les validateurs et qui les aident à corriger les tutoriels. Ce n'est pas une Team officielle.

Normalement, vous ne devriez pas passer par les zCorrecteurs pour vous aider à corriger votre tutoriel. Si vous écrivez plutôt bien et que votre tutoriel ne comporte pas beaucoup de fautes, nous vous montrerons vos erreurs. Mais si vous n'êtes pas très fort en orthographe, les zCorrecteurs vous aideront à corriger votre tutoriel.

Bien entendu, les zCorrecteurs ne sont pas vos boys. Ils ne feront pas le travail à votre place, sinon, vous resterez toujours nul en orthographe. Donc, si vous y allez, emmenez aussi votre bonne volonté, autrement ça ne marchera pas bien.

Je tiens à dire que le passage par les zCorrecteurs n'est pas obligatoire. Mais ça pourrait vous faire gagner du temps, puisque votre tutorial ne sera pas refusé deux ou trois fois pour mauvaise orthographe ^^

Et pour finir, voici l'URL de leur site. N'hésitez pas à consulter leur mode d'emploi :) .

La validation

Avant




Vérifiez l'orthographe



Avant d'envoyer votre tutoriel à la validation, relisez-le ! Nous sommes des validateurs de tutoriels, nous validons le contenu du tutoriel. Ce n'est pas notre rôle de corriger les fautes d'orthographe, de ponctuation et de syntaxe !

Si vous êtes nul en orthographe, demandez à vos parents (ou à n'importe qui de plus doué que vous ^^ ) de relire le tutoriel. Si nous recevons le tutoriel plein de fautes, nous allons vous le refuser pour mauvaise orthographe.

Si vraiment personne ne peut vous aider, vous pouvez demander de l'aide aux zCorrecteurs.


Vérifiez les critères d'acceptation



Avant d'envoyer votre tutoriel, vérifiez qu'il respecte les critères suivants :

  • Vous avez fait un MINI-TUTO : Le mini-tuto doit être achevé.
  • Vous avez fait un BIG-TUTO : Le big-tuto doit contenir au moins 3 mini-tutos consécutifs et doit fournir une base au lecteur. Cela veut donc dire que le tuto doit être bien avancé ! Par exemple, si le tuto est composé de 3 mini-tutos : un sur l'introduction, un sur le contenu, et un en annexe, les mini-tutos d'introduction et d'annexe ne sont pas pris en compte !

Si vous ne respectez pas ces règles, le tutoriel sera immédiatement refusé sans être lu !


Message de validation



Lors de l'envoi du tutoriel à la Validation, vous devez remplir un champ de texte. Ce champ vous sert à passer un message au validateur qui lira votre tutoriel. Vous pouvez y inscrire ce que vous voulez, mais surtout, pensez à y inscrire des informations sur votre tutoriel (vous n'êtes pas sur de la catégorie, précisions à apporter...). C'est très important surtout pour les mises à jour des tutos. Dans ce cas, vous utiliserez ce champ pour indiquer l'objet de la mise à jour.

Pas bien :

ben j'ai corrigé 2/3 fautes et une sous partie


Bien :

J'ai corrigé les fautes d'orthographe signalées dans les commentaires et j'ai modifié dans la sous partie Pour aller plus loin la conclusion en ajoutant quelques liens de sites qui traitent du sujet mais de façon plus avancée.
Merci :)


Pendant



Il est fort possible que votre tutoriel soit refusé. Le validateur qui vous l'a refusé vous expliquera pourquoi dans un MP (que vous recevrez par l'intermédiaire de Zozor).

Prenez en considération les commentaires du validateur. Une fois les modifications demandées effectuées, reproposez votre tutoriel. Il est inutile de préciser quel validateur a refusé le tuto et pour quelles raisons. En effet, nous voyons tous les commentaires des validateurs ainsi que les vôtres.

Cela dit, essayez d'être le plus complet possible dans vos commentaires : « J'ai fait ceci, ça, j'ai retravaillé cela et ceci »

Après



Si votre tutoriel est enfin accepté :) ,vous recevrez les commentaires ajoutés sur votre tutoriel par les membres via un MP de Zozor. Prêtez-y attention. Soit ils sont sympa et là, aucun problème, soit ils sont négatifs, et là, il y a problème. Tâchez de modifier votre tutoriel en conséquence ;)

Vous devez aussi repasser par la validation pour valider les modifications apportées. Essayez d'être le plus complet quant aux modifications effectuées, pour faciliter le travail des validateurs ;)
Voilà, bon tutotage ^^ .

Informations sur le tutoriel

Retour en haut Retour en haut

Créé : Le 26/11/2006 à 17:08:11
Modifié : Le 12/12/2008 à 11:47:03
Avancement : 100%
Licence : Copie non autorisée

78 commentaires