La rédaction

Avant de commencer à écrire, il faut avoir défini le niveau technique du contenu, c’est à dire savoir à qui vous souhaitez vous adresser.

Cela aura des conséquences, puisque si vous visez des débutants vous devrez sans doute introduire et expliciter plus de concepts que si vous vous adressiez à des lecteurs plus avancés. Il vous faudra donc peut-être plus entrer dans les détails et avoir une approche plus avenante si vous visez un public débutant, mais vous toucherez peut-être plus de monde de la sorte aussi. Toutefois, il peut parfois être bon d’éviter de répéter ce qui est déjà enseigné parfaitement dans un autre tutoriel, afin d’avoir des contenus complémentaires ou d’aller droit au but par exemple. N’hésitez donc pas à mentionner un autre tutoriel pour permettre au lecteur d’apprendre les bases de la matière ou, au contraire, pour étendre les notions apprises.

En général, votre choix dépendra avant tout de votre sujet. Si nous prenons l’Introduction aux développements limités par exemple, celui-ci s’adresse à des lecteurs déjà familiers avec les mathématiques, tandis que si nous prenons Administrez vos bases de données avec MySQL, nous voyons que celui-ci s’adresse aussi à des débutants en base de données.

Définir le niveau technique du contenu est donc important.

Mais pour qu’un contenu ait du sens et soit cohérent, il faut déjà qu’il soit structuré.

Un bon plan est donc primordial. Il vous permettra d’organiser vos idées et de savoir où vous allez aller durant la rédaction. Et puis, il permettra au lecteur de savoir ce qu’il pourra trouver dans votre contenu et où.

Généralités

Un contenu peut se composer d’une ou plusieurs parties, pouvant comprendre un ou plusieurs chapitres, eux-mêmes subdivisés en une ou plusieurs sections.

Il y a donc trois niveaux différents :

• Partie (qui peut comprendre une introduction et une conclusion) ;
• Chapitre (qui peut également comprendre une introduction et une conclusion) ;
• Section.

Les sections forment le coeur de votre contenu. C’est dans celles-ci que vous écrirez le contenu de votre tutoriel.

Si nous illustrons brièvement en prenant l’exemple de ce guide, « Contribuer au contenu » est une partie contenant plusieurs chapitres nommés : « Généralités », « Amorce de la rédaction », etc. dont vous êtes en train de lire une section.

Types de structures

Il y a trois types de structures de contenus :

1. Vous pouvez créer un tutoriel comprenant une ou plusieurs partie(s), un ou plusieurs chapitre(s) et des sections s’y attachant. C’est ce que nous appelons, dans notre jargon hérité du Site du Zéro, un « big-tuto ». C’est le cas de ce tutoriel.

2. Vous pouvez créer un tutoriel composé d’une ou plusieurs partie(s) et de sections (sans chapitres, donc). Ce cas de figure est ce que nous appelons un « moyen-tuto ».

3. Enfin, vous pouvez créer un tutoriel uniquement composé de sections, appelé « mini-tuto ». Il suffit pour cela de ne créer que des sections. Cette structure est aussi majoritairement utilisée pour les articles.

Vous constatez donc qu’il est vraiment possible d’adapter la structure de votre contenu selon vos envies.

Illustrons tout cela !

Création d’un plan

Avant de s’attaquer à la création d’un plan sur ZdS, il peut être bon d’en avoir esquissé un au brouillon, ne serait-ce que dans ses grands traits. Pour cela, une méthode consiste à prendre des notes sur le sujet que vous avez choisi puis de les regrouper en blocs de sorte à ce que ces blocs puissent former des parties de votre contenu. Ces notes vous permettront par la suite de les remplir. Enfin, il faut organiser ces parties de manière cohérente (qu’il ne faille pas lire la dernière pour comprendre la première par exemple ). Par ailleurs, vous pouvez aussi avoir une problématique qui vous aidera à organiser vos propos.

Pour cet exemple, nous avons créé un tutoriel avec les paramètres par défaut, que nous avons appelé « Contenu ». Il semble bien vide pour le moment puisque nous n’avons écrit ni d’introduction ni de conclusion :

Nous sommes alors à l’accueil de notre contenu. Le lien « Éditer » permet d’éditer celui-ci (changer le titre, l’introduction, etc.) en nous ramenant sur la page de création. Juste en dessous, des liens permettent d’ajouter respectivement une partie et une section. Nous allons ajouter une partie. Cliquez donc sur le lien « Ajouter une partie ». Nous arrivons sur une page où il faut saisir le titre de celle-ci. De plus, nous pouvons préciser une introduction et une conclusion. Validons. La partie s’affiche comme convenu :

Vu que nous sommes dans une partie, nous pouvons ajouter soit un chapitre, soit une section comme l’illustre les liens dans le menu de gauche. Par ailleurs, nous pouvons éditer, déplacer ou même supprimer notre partie, toujours avec les liens respectifs du menu de gauche. Enfin, il nous est possible de nous déplacer dans notre contenu en nous servant du sommaire sur la gauche ou bien de la barre juste au-dessus (encadrés en vert). Par exemple, en cliquant sur le titre de notre contenu, nous reviendrons à l’accueil de celui-ci et verrons notre début de plan.

Nous allons maintenant ajouter un chapitre et dans ce chapitre nous allons ajouter une section, en procédant de la même façon. Voici le résultat :

Comme nous l’avons dit précédemment, les sections sont un peu particulières, car c’est là que l’on rédige véritablement le contenu. Ainsi, pour supprimer, déplacer ou éditer celles-ci, il suffit de cliquer sur les boutons appropriés (encadrés en rouge dans l’illustration ci-dessus). Du coup, elle n’ont pas de page propre contrairement aux parties et au chapitres. Comme nous sommes cette fois-ci dans un chapitre, le menu de gauche permet de modifier celui-ci.

Si vous vous souvenez bien de ce que nous avons dit, notre contenu est un « big-tuto » vu qu’il s’organise sur trois niveaux.

Organiser les sections

Enfin, il est possible et même conseillé de structurer vos sections en utilisant les balises titres du zMarkdown. Celles-ci sont au nombre de quatre :

# Titre de niveau 1

## Titre de niveau 2

### Titre de niveau 3

#### Titre de niveau 4

Ces titres n’apparaissent pas dans le plan, mais sont vraiment utiles pour diviser, organiser et aérer le contenu des sections.

En définitive, plus votre contenu sera structuré, plus il sera cohérent, dynamique et clair à suivre pour le lecteur.

Pour réussir à faire comprendre au lecteur un sujet, il convient avant tout d’être pédagogue. Il n’existe évidemment pas de pédagogie « ultime », qui conviendrait à tout type de lecteur. C’est la raison pour laquelle nous n’imposons pas de style didactique, mais essayons toutefois de donner quelques éléments à tenir à l’œil.

Nous n’abordons pas ici les grandes théories de la pédagogie, n’hésitez donc pas à approfondir votre compréhension de la pédagogie en vous renseignant sur ces différentes théories.

Ne partez pas du principe qu’être bon dans votre discipline fait de vous un bon pédagogue !

Vous êtes plein d’enthousiasme pour transmettre des connaissances dans une matière que vous aimez, que vous maîtrisez du bout des doigts. Vous êtes rigoureux et méthodique. Toutefois, gardez à l’esprit que votre lectorat n’a pas le même bagage que vous.

Illustrez les notions complexes avant de les expliquer

Pour les notions complexes, il est habituellement plus aisé pour le lecteur de comprendre ces notions en le mettant dans une situation illustrative au préalable (même si l’exemple est caricatural, généralement cela marche même mieux) et en scindant les notions pour en expliquer point par point les éléments caractéristiques. Une fois cette mise en bouche faite, il vous sera plus facile d’expliquer les éléments théoriques et d’approfondir la notion. N’hésitez pas à reprendre votre exemple pour en illustrer les approfondissements s’il y a lieu.

Rendez votre pédagogie accessible

À la manière d’une présentation orale (qu’il s’agisse d’une soutenance de thèse ou autres), utilisez un langage direct et pensez à toujours introduire — dans chaque chapitre — ce qui sera enseigné et comment les notions seront enseignées.

Essayez de fournir l’objectif de la notion apprise, cela permet de faire des liens entre les notions et même entre les matières (entre des tutoriels différents, par exemple). Ce qui est enseigné doit avoir du sens pour le lecteur. N’hésitez pas à indiquer des références pour expliquer ou appuyer ce que vous dites.

Mettez les lecteurs à l’épreuve !

Ce n’est pas toujours possible selon le sujet du contenu. Mais si votre contenu s’y prête (par exemple, un tutoriel sur un langage, un cours de chimie, etc.), mettez en place des exercices afin de mettre en pratique les notions apprises par des TPs pertinents. Offrez aussi si possible des pistes de réflexion pour étendre l’objet de l’exercice. Par exemple, pour optimiser le référencement d’un site web, la vitesse d’exécution de l’application, etc.

Autres remarques

Selon le sujet abordé dans votre contenu, prêtez attention à divers éléments :

• La pertinence des exemples ;
• La fluidité de votre texte et l’évolution logique de votre contenu (plus une lecture est aisée et l’approfondissement du sujet logique, plus le lecteur sera à l’aise pour comprendre le sujet abordé ou l’enseignement du tutoriel) ;
• Des illustrations, tableaux ou autres, lisibles et légendés ;
• Vous pouvez également utiliser des vidéos en complément de votre contenu textuel, cela peut être très utile d’avoir un autre support.

La mise en forme d’un contenu n’est pas à négliger.

En effet, celle-ci permet de mettre en valeur certaines parties, de dynamiser la lecture ou encore d’illustrer le contenu. Par exemple, un texte bien organisé et aéré donnera plus envie que le contraire n’est-ce pas ?

Ainsi, pour mettre en valeur un mot, nous pouvons le mettre en gras par exemple. Pour insérer une illustration, il suffit de l’importer dans la galerie et de se servir de la balise adéquate. Ou encore, il est aussi possible d’ajouter des tableaux. Il existe même des blocs spéciaux (information, question, attention, erreur et masqué) !

Comme nous l’avons déjà vu au cours de ce tutoriel, le zMarkdown est l’outil de mise en forme utilisé. Encore une fois, nous vous laissons explorer l’éditeur et regarder la documentation pour vous familiariser avec.

Dans un contenu, les références sont indispensables, pour deux principales raisons.

Proposer des contenus complémentaires au lecteur

Tout d’abord, elles servent à proposer des contenus complémentaires au lecteur, que ce soit sur des prérequis ou pour aller plus loin. Nous pouvons donc les trouver dans l’introduction, le corps ou bien la conclusion d’un contenu selon leur but.

Dans l’introduction

Comme nous l’avons vu, les prérequis nécessaires à la bonne compréhension du contenu doivent figurer dans l’introduction. L’auteur peut alors en profiter pour proposer des contenus permettant de s’approprier les notions nécessaires. Ainsi, en se formant avec les documents proposés, le lecteur devrait pouvoir suivre dans de bonnes conditions. Voici un exemple de tutoriel avec des références en introduction.

Vous pouvez aussi donner des références en lien avec la motivation de ce que vous allez exposer. En effet, l’introduction servant à délimiter le sujet et à en donner les raisons d’être, il se peut que des références permettent de mettre en relation les questions posées, les outils utilisés ou les points de vues adoptés.

Dans le corps

Dans le corps, les auteurs peuvent vouloir référencer des contenus en lien avec le sujet traité, que ce soit pour compléter leurs propos ou pour aller plus loin. Cela leur permet de ne pas trop s’éloigner de leur fil rouge tout en ouvrant le champ de vision du lecteur. Par exemple, le tutoriel précédemment mentionné contient des références au cours du contenu.

Dans la conclusion

Enfin, la conclusion peut aussi contenir des références à des contenus en lien avec le sujet traité pour renforcer les connaissances, proposer des alternatives ou aller plus loin. Par exemple, la conclusion de ce tutoriel contient des références permettant d’approfondir le sujet.

Pour la valeur scientifique

Mais avant tout, les références sont un élément important pour la scientificité et la solidité d’un écrit.

Elles permettent tout d’abord d’inscrire le contenu dans un corpus déjà existant, ce qui permet notamment de pouvoir se concentrer sur les détails nouveaux ou relevant purement du sujet plutôt que de tout reconstruire sachant que la littérature déjà existante a fait ce travail.

Cela donne aussi une base commune de culture et d’outils aux lecteurs. C’est important puisque, même si la liste des prérequis est éclairante, il se peut que le lecteur se pose une question à laquelle il aurait directement réponse dans les références bibliographiques. C’est donc un gain de temps non négligeable.

Enfin, si le sujet est bien maîtrisé par l’auteur, mettre des références ne devrait demander que peu d’efforts puisqu’on invente (très, très) rarement tout tout seul. Demandez vous donc simplement ce qui vous a aidé dans votre apprentissage et vous semble important.

Ces références sont en général mentionnées au cours du contenu ou bien à la fin. Ce tutoriel ou encore celui-ci en contiennent.

Comme vous avez pu le voir, les références sont importantes et peuvent être présentées sous différentes formes (listes, notes de bas de page, etc.) du moment que c’est assez clair pour le lecteur.

Vérifiez vos sources !

Il devrait être évident que l’on ne cite et met en référence des textes que si on les a lu et étudiés. Il arrive que certains contenus comportent des erreurs. La vérification de la pertinence des références est donc primordiale. Si vous vous lancez dans un sujet que vous venez à peine de découvrir, évitez de rédiger dessus.

Dans cette partie, nous allons aborder quelques points importants en ce qui concerne la rédaction.

Essayez d’avoir une certaine souplesse en ce qui concerne votre plan

Très souvent, l’auteur a tendance à s’atteler à la rédaction dès qu’il dispose d’un plan paraissant approprié. Cependant, durant la rédaction, cela peut donner lieu à des doublons dans différentes parties du contenu, amenenant parfois l’auteur à réécrire des pans entiers de texte car le contenu ne correspond plus à la structure initiale. Pour éviter cela, il est judicieux de garder une certaine souplesse dans la préparation de la structure de votre contenu afin qu’il puisse s’adapter selon l’évolution de la rédaction, au besoin.

Rédigez votre introduction générale en dernier

L’introduction générale du contenu est bien plus aisée à écrire lorsque le corps du contenu est terminé. Comme pour une dissertation, le fait d’avoir une version (même un premier jet) stable du corps de votre contenu vous permet de savoir avec une certaine certitude les points abordés, cela devient du coup bien plus facile pour estimer les prérequis, bien introduire le sujet, motiver le lecteur, etc.

Evitez d’utiliser la première personne du singulier… si vous êtes plusieurs à écrire

Cela peut sembler logique mais c’est une remarque assez courante.

La seconde relecture et la réécriture

Il est très fréquent que les auteurs envoient leur contenu en validation trop rapidement. Le problème se pose parfois au niveau des tournures de phrases, certaines peuvent être assez lourdes ou trop longues.

L’une des meilleures façons de s’assurer que le contenu est fluide à la lecture pour l’auteur est de rédiger en plusieurs passes :

1. Dans un premier temps, rédigez votre contenu « normalement », sans spécialement essayer d’avoir de belles tournures. Allez droit au but et finissez les sections ou chapitres concernés.
2. Ensuite, laissez passer quelques jours sans relire ou réécrire le contenu que vous avez rédigé. Vous pouvez, bien évidemment, continuer la rédaction d’autres chapitres.
3. Enfin, revenez sur le contenu précédemment rédigé afin de réécrire les passages qui devraient l’être ou d’expliciter certaines notions.

N’hésitez pas à faire plusieurs cycles de relecture/réécriture jusqu’à ce que vous estimiez qu’il n’y a plus de modification à effectuer.

Dernier conseil : n’hésitez pas à contacter un membre du staff ou à mettre le contenu en bêta

Vous avez des doutes quant à la rédaction ? N’hésitez pas à demander de l’aide ! En effet, nous sommes à votre disposition pour vous guider plus spécifiquement dans la rédaction. Il nous sera possible, de la sorte, de vous fournir des remarques portant tant sur la structure de votre contenu que sur le style ou tout autre conseil dont vous estimez avoir besoin.

La page qui regroupe les membres du staff.

Vous pouvez aussi mettre le contenu en bêta afin d’obtenir des retours des membres sur le style, la structure ou le fond de votre contenu. Nous aborderons cela plus en détail dans le prochain chapitre.