Comment écrire un bon tutoriel ?

Bonjour à tous,

J'ai commencé (il y a 2 semaines) la rédaction d'un tutoriel dont l'intitulé est Comment écrire un bon tutoriel ?.

J'aimerai obtenir un maximum de retour sur celui-ci, sur le fond ainsi que sur la forme, afin de proposer en validation un texte de qualité.

Si vous êtes intéressé, cliquez ci-dessous :

En fait, j'ouvre ce sujet pour que chacun puisse partager son expérience d'auteur et expliquer comment il s'y prend pour produire un bon cours (à ses yeux). L'objectif n'est pas de générer un modèle de l'auteur parfait, loin de moi cette idée, mais simplement d'échanger sur les méthodes de rédaction, sur quand les utiliser…

Pour tout vous dire, c'est cet article qui a initié ce sujet.

Let's go!

Hello
Merci pour le lien et l'article, je ne connaissais pas ce site, il a l'air interessant.
Pour ce qui est de mon expérience perso pour la rédaction de tuto:

Au niveau de la motivation:

Ecrire un tuto, c'est long, avec des parties chiantes (mises en forme, devoir expliquer des choses qu'on trouve évidentes,....) et ma motivation est souvent en dent de scie.
Du coup il vaut mieux faire un tuto sur un sujet qu'on aime (et non pas un tuto sur commande).

De plus, j'essaie de profiter au maximum des moments où ma motivation est forte. Il m'arrive parfois de mettre quelques trucs à l'écrit, en brouillon, quand j'ai 10 min de motivation, d'autres fois j'en profite pour mettre en forme… Si j'avais attendu d'avoir une motivation au top, j'aurais jamais commencé. De plus, c'est plus facile de continuer un truc déjà commencé que de se motiver à commencer sur une page blanche.

Autre motivation possible: l'auto-formation. On dit souvent qu'il faut maitriser un sujet pour en faire un tuto, pourtant lorsqu'on commence à apprendre un sujet, c'est très formateur d'essayer de l'expliquer à quelqu'un. Ecrire un tuto peut être une bonne idée. Evidemment, il faut se dire que le tuto ne sortira que beaucoup plus tard, lorsqu'on aura suffisamment maitrisé son sujet et qu'on aura corrigé les erreurs de débutant qu'on a forcément écrites au début. Mais à ce moment-là, on ne partira pas d'une feuille blanche, et on aura beaucoup appris rien qu'en essayant de rédiger le tuto.

Au niveau de la pédagogie:

Dans un tuto, j'essaye toujours de partir de quelque chose que le lecteur connait, pour l'amener par un chemin continu vers ce que je veux lui apprendre. Ainsi, je ne le perds pas, il peut toujours raccrocher les nouvelles notions apprises à quelque chose avec lesquelles il est familier.
Par exemple pour la dérivée: je ne vais pas directement parler de limite de taux d'accroissement, je vais partir de quelque chose de connu par un collégien: la pente d'une droite. Puis je l'amène à se demander ce qui se passe si on n'a pas une droite mais une courbe, … et j'arrive donc après sans trop de heurts à la formule de la dérivée (avec les h et les limites)

Cela implique de bien cerner le public qu'on vise et les prérequis qu'on demande pour le tuto. On n'écrit pas le même tuto pour un lycéen ou pour un doctorant…

J'ai un autre principe pédagogique que j'essaye d'appliquer quand j'explique quelque chose: il ne faut pas que le lecteur se pose la question "Pourquoi il me parle de ça". Ou alors, quand il se la pose, j'y réponds tout de suite après. En clair, j'essaie de ne jamais parler de quelque chose sans dire pourquoi j'en parle. Rien ne doit sortir comme par magie du chapeau.

En contre-exemple à cela, il y a les cours scolaires, qui commencent souvent par un gros chapitre "Définitions" avec le plan Définitions-Théorème-Démonstration-Lemme.... On arrive sur ça directement, on ne sait pas pourquoi on nous parle de ça, ce n'est relié à rien.... (Exemple classique du bouquin de maths qui commence par: "Soit E un ensemble et * une loi de composition interne....", ou de la multiplication de matrices qu'on pose sans l'expliquer ("C'est comme ça qu'on fait une multiplication") et après, oh miracle, ça marche très bien pour parler d'applications linéaires…).
C'est le genre de trucs que j'essaie d'éviter absolument, d'ailleurs pour moi un tuto n'est pas un cours, si une personne cherche un tuto c'est parce que son cours ne lui suffit pas donc cela ne sert à rien de reprendre la même logique.

PS: d'ailleurs pour la pédagogie, je recommande la lecture de ce tutoriel (les pratiques pedagogiques efficaces) qui parle de psychologie cognitive et de l'apport de cette science à l'éducation

Merci !

Je me demandais : faut-il faire le lecteur se poser des questions ? En expliquant tout en détails, dans l'ordre, il comprendra, mais retiendra-t-il ? Tandis que si j'introduis des passages un peu obscurs, que j'éclaire quasiment instantanément (via une balise "question" par exemple), est-ce que ça ne fait pas participer le lecteur en quelque sorte ? Je me souviens par exemple d'un cours de Mathieu Nébra, sur le C++ je crois, dans lequel certains passages soulevaient des questions… auxquelles il répondait quelques lignes en dessous. Donc, d'une part ça m'interpellait et me faisait me concentrer sur le cours, et d'autre part, ça me rendait satisfait d'obtenir rapidement une réponse à ma question : c'était, je pense, plus agréable que d'avoir le résultat tout de suite, au point de ne s'être même pas questionné sur la chose.

Ce n'est qu'une hypothèse bien sûr.

Salut !

Pour ma part, j'essaie de prévenir les questions plutôt que de les laisser être posées et "devoir y répondre", sans quoi je risque de me retrouver avec un tutoriel qui n'a plus de rythme parce que brisé par les questions, justement. Et cela implique que dans certains cas, je cache la question et enchaîne rapidement sur l'explication.

Le premier truc à savoir pour rédiger un bon tutoriel, c'est de se rappeler qu'un tutoriel n'est pas un cours : à la fin d'un tutoriel, le lecteur doit savoir faire quelque chose qu'il ne savait pas faire avant. En clair, il doit apprendre des méthodes, des procédures, une manière de penser, des techniques, bref : du savoir-faire. Et le premier qui me dit qu'aucun de mes tutoriels ne semble respecter ce que je viens de dire risque de ne pas garder son intégrité physique très longtemps.

Dans ces conditions, le lecteur doit comprendre à quoi ça sert, pourquoi on cherche à lui apprendre ça. Pour cela, il vaut apprendre chaque notion en deux parties :

• une première qui indique à quoi sert ce qu'on va apprendre ;
• et une autre qui enseigne le savoir-faire.

La première partie doit expliciter les situations dans lesquelles on applique le savoir-faire, et pourquoi. Grosso-modo, elle doit indiquer :

• à quel catégorie de problèmes ou de situations doit s'appliquer le savoir-faire à apprendre ;
• quelles sont les conditions nécessaires pour que l'on puisse appliquer la procédure et pourquoi ;
• quel est le but du savoir-faire à apprendre ;
• etc.

Mine de rien, cette première partie est souvent passée sous silence ou survolée : rares sont les tutoriels qui commencent par donner beaucoup d'exemples de situations ou de problèmes dans lesquels on peut appliquer ce qu'on va apprendre.

Cette organisation en catégorie de problèmes -> solution est assez intuitive quand on prend l'habitude. Par exemple, c'est ce que j'ai fait pour "Fonctionnement d'un ordinateur de zéro". Après tout, chaque technologie inventée en architecture des ordinateurs l'a été pour résoudre un problème bien précis, ce qui fait qu'il est très facile d'utiliser cette organisation : (catégorie de) problème à résoudre -> solution.

Peut-être ai-je mal compris ce que tu sous-entendais, mais n'est-il pas préférable de mélanger les deux ? Sinon, me semble-t-il, un tutoriel serait "simplement" un cours précédé (suivi ?) d'exemples d'application du contenu du cours.

Pourrais-tu expliciter la notion de "savoir-faire" ? Tu veux dire ne pas simplement acquérir des connaissances, mais être en mesure de les mobiliser et les utiliser ? Cela passe-t-il par des exemples (uniquement ?) ?

Merci !

C'est ça : les connaissances acquises dans un tutoriel ne doivent pas rester inertes et être apprises pour elles-mêmes (même si c'est une bonne chose), et on doit les réutiliser, les appliquer, les mobiliser. Cela peut signifier qu'on doit pouvoir produire quelque chose à partir de ces connaissances (comme dans l'apprentissage de la programmation), ou les utiliser pour interpréter ou expliquer des situations nouvelles (matières scientifiques).

En fait, l'organisation en problème -> solution sert à organiser le cours, et n'a rien à voir avec des exercices ou exemples. C'est une idée que j'ai plus ou moins induite lors de la rédaction de mes tutoriels.

Par exemple, prenons un cours d'architecture des ordinateurs qui aborde le binaire. Sans ma méthode, le cours commencerait directement par expliquer comment représenter des nombres en binaire, sans plus de précision (erreur que j'ai personnellement faite…). Or, si nos ordinateurs utilisent le binaire, c'est qu'il y a une bonne raison, et un bon cours d'architecture des ordinateurs doit expliquer que le binaire est une solution technique qui répond à un problème précis : comment représenter les données dans un ordinateur de manière efficace et fiable.

Et ce genre de choses s'applique à beaucoup de choses en architecture des ordinateurs :

• pourquoi utilise-t-on le renommage de registre au lieu de simplement ajouter des registres architecturaux ?
• pourquoi utiliser des registres alors qu'on pourrait se contenter des adresses mémoire ?
• pourquoi renommer les registres au lieu d'ajouter des registres architecturaux ?
• pourquoi les processeurs RISC préfèrent limiter leur jeu d'instruction alors que les processeurs CISC préfèrent faire l'inverse ?
• etc.

En fait, virtuellement tout ce qui a rapport à l'architecture des ordinateurs a été inventé pour répondre à un problème. Le renommage de registre, l’exécution dans le désordre, chaque mode d'adressage, etc; sont des solutions techniques.

Et c'est un peu la même chose pour l’électronique numérique/analogique : les composants ont tous une utilité bien précise, et permettent de répondre à un besoin bien précis. Par exemple, les diodes ne s'utilisent pas n'importe quand : elles servent à empêcher le courant de passer dans un sens, ce qui correspond à des catégories de besoins bien précis. Même chose avec un multiplexeur : on n'utilise un multiplexeur que dans un contexte bien précis, pour répondre à un besoin.

Dans ces conditions, organiser le cours en suivant ce schéma problème -> solution permet de bien enseigner le contexte d'utilisation de la connaissance, les situations dans lesquelles celle-ci est pertinente. L'idée principale c'est de montrer pourquoi on a inventé ça, d'où ça sort, quelle est l'utilité qui a mené à inventer ce qu'on va apprendre, qu'est ce que ce que je vais apprendre me permettra de faire ou de gérer.

J'ai récemment vu que certaines méthodes pédagogiques utilisent ce principe de problème -> solution. Le premier exemple est celui de l'apprentissage des quatre opérations fondamentales : addition/soustraction, et multiplication/division. Il existe une méthode d'apprentissage du calcul qui explicite au maximum les différentes catégories de problèmes mathématiques qui se résolvent avec une addition/soustraction ou une multiplication/divisions : on l'appelle sous le nom anglais de Schema Based Intervention. Et j'en parle dans mon futur tutoriel sur la pédagogie du calcul.

Après, on peut aussi généraliser cette méthode de problème -> solution dans d'autres situations.

On peut peut-être appliquer ce principe aux théories scientifiques, même si j'ai quelques doutes. Après tout, si une théorie a été inventée, c'est souvent pour répondre à un besoin : expliquer des faits que d'anciennes théories n'arrivaient pas à résoudre. Dans ces conditions, montrer les besoins, c'est à dire les expériences inexplicables avec des théories déjà connues avant d'introduire la nouvelle théorie est clairement une bonne chose : cela donne des indices sur le domaine de validité de chaque théorie, et permet d'induire son contexte d'utilisation. Après, je dois avouer que je ne suis pas trop sûr.

Et ce principe peut aussi s'appliquer pour l'enseignement de l'histoire. Les événements historiques sont souvent le produit de causes bien précises qui donnent souvent les mêmes effets : tel problème économique déclenche des migrations ou des guerres, tel problème religieux déclenche une guerre, etc. On peut parfaitement considérer que les événements historiques sont autant de solutions que les hommes de l'époque ont tenté face à des problèmes bien précis.

Certains chercheurs ont tentés de catégoriser les différents événements historiques et leurs causes et ont identifié des catégories de problèmes historiques récurrents résolus par des solutions générales comme des guerres ou des migrations. Après tout, l'histoire se répète, comme diraient certains.

De mémoire, certains cursus qui conçus avec la méthode du Direct Instruction utilisent cette technique pour l'apprentissage de la guerre d'indépendance américaine : les divers actes imposés par l'Angleterre aux colonies américaines (les Intolerable Acts) qui ont menés à la guerre étaient autant de réponses de l’Angleterre face à des problèmes économiques et sociaux. Et l'expliciter vaut mieux que simplement décrire les divers actes

Dans ce dernier cas, le schéma problème -> solution est surtout utile pour expliciter les liens de causalités, expliquer pourquoi les choses sont ce qu'elles sont, pourquoi elles se sont passées comme ça.

La question est vaste. La façon de rédiger un tutoriel va dépendre du type de sujet (technique, discussion), du public visé (débutant, avancé), de la maîtrise que l'on a du sujet (et surtout de la maîtrise que l'on du du sujet par rapport aux autres sujets du même domaine, comment il est placé dans ce domaine).

Je suis d'accord sur les premiers points donnés par Looping :

• la motivation, je n'écris que sur des sujets qui m'intéresse ;
• la formation, j'apprend toujours quelque chose en écrivant un tuto (si ce n'est pas le cas, c'est que je n'ai pas assez bossé les sources pour écrire ce tuto );

Ensuite, ma façon de travailler est très variable. Je peux prendre des notes lorsque j'étudie un sujet et convertir par la suite mes notes en article (par exemple mes articles sur Boost.Graph ou Qt Android). Je peux partir sur une thématique parce qu'une question reviens souvent (signaux et slots de Qt, déployer une appication Qt) ou parce que c'est l'actualité (C++11, C++14). Ou cela peut être un sujet qui m'intéresse et que je pars sur la rédaction d'un article pour l'étudier (par exemple l'article en cours sur l'entity-component-system).

Pour la forme des tutos, je ne suis pas fan de l'approche SdZ, avec un côté "on discute entre pote", des smileys, des questions écrites dans le tutos et aux quelles ont répond ensuite, etc. La forme question-réponse n'est pas à mon sens de l'interactivité avec le lecture. Un lecteur est interactif s'il tape du code à côté ou s'il se pose des questions qui ne sont pas abordé. Je préfère garder un côté formel. Par contre, j'aime beaucoup les images et les schémas, je trouver que cela permet de mieux comprendre les choses.

Par contre, je ne suis pas trop d'accord sur l'approche "guy". La majorité des lecteurs de mes tutos sont des personnes qui arrivent dessus suite à une recherche sur internet. Elles viennent parce qu'elles sont intéressé par le sujet et ont des questions spécifiques. Cela ne sert à rien de lui expliquer à quoi cela sert, elle le sait, elle est là pour cela (il faut contextualiser, mais cela tiens en 1 ou 2 lignes en général, pas plus). De même, il n'est pas nécessaire d'expliquer les situations dans les quelles elle va pourvoir appliquer ce qu'elle apprend dans le tuto. Elle le sait déjà, elle est la pour cela.

Quand à la pédagogie expliquée par guy, je ne la remets pas en cause, mais je trouve que cela ne s'applique pas aux tutos (tout au moins, au mien). Cela ne sert à rien d'avoir une pédagogie pour que le lecteur retienne les choses. On n'est pas à l'école, un tuto est disponible 24h/24, quand on veut, en un simple clic. C'est pour cela que je préfère des tutos assez descriptif, où le lecteur assimile les grandes idées à la première lecture, puis retrouve facilement les informations lors de ses 10 prochaines lectures (ce qui est facilité par les codes, schémas, tableaux)