# Repérer les lacunes d’un tutoriel à partir des fils de commentaires YouTube

Reliez un commentaire à un passage précis de la leçon avant de modifier un tutoriel. Lisez les réponses publiques et le texte de la leçon orale. Regardez aussi les images. Consignez ensuite vos constats. Il manque peut-être une explication dans la leçon. La leçon explique peut-être déjà le point soulevé. Ou les faits vérifiés sont peut-être trop limités pour en juger.

Une lacune dans une leçon peut être une explication manquante, une formulation peu claire ou une configuration qui ne correspond pas à celle de la leçon. Un tableau des lacunes de la leçon se compose de plusieurs lignes. Chaque ligne relie un commentaire à la leçon, à une décision et à un test.

Utilisez l’Actor [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper) pour collecter les commentaires publics. Un Actor est un programme hébergé qui collecte des lignes de données issues des sources. Une Task est un ensemble de paramètres d’entrée enregistré. La [Task publique d’analyse des commentaires vidéo](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis) fournit seulement des paramètres de départ. Elle ne prouve pas que la vérification s’effectue toute seule. L’Actor n’évalue pas la leçon. Ce travail vous revient.

Ces limites correspondent aux versions publiques vérifiées le 2026-10-13. Les versions ultérieures peuvent changer. Lisez les résultats de l’exécution pour la version que vous utilisez.

## Collecter un échantillon limité de commentaires

La version publique 1.1.6 de l’Actor de commentaires accepte l’adresse ou l’identifiant d’une vidéo publique connue. Vous pouvez fournir de 1 à 100 adresses dans `startUrls`. Réglez `maxCommentsPerVideo` entre 1 et 1 000. Ce nombre constitue le plafond. Le plafond correspond au nombre maximal de commentaires de premier niveau que vous demandez. Un commentaire de premier niveau est un commentaire qui n’est pas une réponse. Réglez `commentSortMode` sur `top`, `newest` ou `both`. Top désigne les commentaires que YouTube classe en premier. Newest désigne les commentaires les plus récents. Activez ou désactivez `includeReplies`. Lorsque les réponses sont activées, `maxRepliesPerComment` accepte une valeur de 1 à 100. Une réponse est une réaction placée sous un commentaire de premier niveau. Les lignes de réponses s’ajoutent aux autres lignes. Elles ne sont pas décomptées du plafond des commentaires de premier niveau.

La Task enregistrée contient toujours une vidéo de chanson comme exemple, un plafond de 250, les réponses activées et un maximum de 10 réponses. Remplacez cet exemple avant d’évaluer un tutoriel.

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"],
  "maxCommentsPerVideo": 250,
  "commentSortMode": "both",
  "includeReplies": true,
  "maxRepliesPerComment": 10
}
```

Collecter un échantillon limité de commentaires

Pour la première vérification, utilisez un tutoriel dont vous savez déjà qu’il est public. Fixez le plafond à 2. Réglez `commentSortMode` sur `both`. Réglez `includeReplies` sur false. N’incluez pas l’ancien plafond de réponses.

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=YOUR_TUTORIAL"],
  "maxCommentsPerVideo": 2,
  "commentSortMode": "both",
  "includeReplies": false
}
```

Collecter un échantillon limité de commentaires

Un autre test de contrôle limité a utilisé une vidéo pédagogique, un plafond de 2 et les 2 modes de tri. Il a enregistré 2 commentaires de premier niveau contenant du texte. Une ligne correspondait à Top. Une ligne correspondait à Newest. Chaque ligne comportait un `commentId`. `publishedAt` avait la valeur null. OUTPUT indiquait `commentsWritten` à 2 et `repliesWritten` à 0. `stopReasonCounts` contenait `requested_comment_limit_reached`. Ne cherchez pas un champ unique nommé `stopReason`.

`commentsWritten` à 2 signifie que 2 lignes de commentaires ont été enregistrées. `repliesWritten` à 0 signifie que 0 ligne de réponse a été enregistrée. Ce zéro est un décompte propre à cette exécution. `publishedAt` à null signifie que la date n’a pas été fournie. Une valeur inconnue n’est pas un zéro. N’enregistrez pas une date vide sous la valeur 0.

Ce test de contrôle ne prouve pas que les réponses sont exportées. Le test de validation ne couvrait pas les réponses automatiques. Cette méthode ne considère pas le fichier comme une reconstitution du fil de discussion. Lorsqu’une réponse peut changer le sens, ouvrez la page publique de lecture de la vidéo et lisez-la. Si une réponse n’y figure pas, laissez-la manquante. N’inventez pas son contenu.

Conservez [l’ordre de la source et le plafond](/fr/articles/%C3%A9chantillonnage-commentaires-youtube/) dans vos notes. Le plafond permet de sélectionner un petit échantillon. Il ne sert pas à déterminer le problème le plus important de la leçon. Votre vidéo peut renvoyer une répartition différente d’une ligne Top et d’une ligne Newest.

Chaque ligne de commentaire doit comporter les champs suivants :

| Champ | Signification |
| --- | --- |
| `videoId` | L’identifiant public de la vidéo |
| `videoUrl` | Le lien public de la vidéo |
| `commentId` | L’identifiant public du commentaire |
| `sortMode` | Top ou Newest pour cette ligne |
| `text` | Le texte du commentaire |
| `authorChannelId` | L’identifiant public de la chaîne de l’auteur, lorsque la source le fournit |
| `publishedTimeText` | L’indication temporelle affichée avec le commentaire, lorsqu’elle est présente |
| `publishedAt` | Une date et une heure. La valeur null signifie qu’elles sont inconnues, pas égales à zéro |
| `scrapedAt` | Le moment où la ligne a été collectée |
| `status` | Le résultat obtenu pour la ligne |

Si une entrée n’était pas disponible, OUTPUT le signale. Lisez `status` avant d’évaluer une ligne. Si le texte manque, conservez cette ligne à part. Ne complétez pas le texte. Si `authorChannelId` manque, l’auteur est inconnu. N’inventez pas une personne. Un auteur manquant ne signifie pas zéro spectateur.

Un nombre de commentaires n’est pas un nombre d’apprenants. Ce n’est pas une mesure de leur niveau de compréhension. Si aucun commentaire n’est enregistré, `commentsWritten` vaut 0. Ce zéro signifie que vous n’avez pas d’échantillon de commentaires. Il ne signifie pas que les spectateurs ont compris la leçon. Ne transformez pas l’échantillon en un score de sentiment.

## Collecter les sous-titres horodatés du même tutoriel

La version publique 0.1.43 de l’Actor de transcription accepte les paramètres connus `startUrls`, `preferredLanguages` et `outputFormats`. Utilisez le même tutoriel que pour les commentaires. Remplacez toute la liste `startUrls`. Ne laissez pas la vidéo de chanson fournie en exemple dans la liste. Demandez `json` lorsque vous avez besoin de segments horodatés. Un segment est un morceau de sous-titre associé à un intervalle de temps.

```json
{
  "startUrls": ["https://www.youtube.com/watch?v=YOUR_TUTORIAL"],
  "preferredLanguages": ["en"],
  "outputFormats": ["json"]
}
```

Collecter les sous-titres horodatés du même tutoriel

`preferredLanguages` exprime une préférence. L’exemple utilise `en` pour l’anglais. Modifiez cette valeur si vous préférez une autre langue de sous-titres. Ce champ ne traduit pas la leçon.

Un test de contrôle de transcription sur la même vidéo pédagogique a réussi. Il a renvoyé une piste manuelle en anglais non vide et des segments horodatés. Une piste manuelle est un fichier de sous-titres préparé par une personne. Le test montre que cette version peut renvoyer le texte des sous-titres et leur horodatage lorsqu’une piste existe. Il ne montre pas que votre vidéo dispose de sous-titres. Cet article ne reproduit pas le texte réel des sous-titres.

Utilisez les champs publics des segments `startSeconds`, `endSeconds`, `durationSeconds` et `text`. Lisez `endSeconds` dans le segment. Si `durationSeconds` est présent, additionnez `startSeconds` et `durationSeconds`. La somme doit correspondre à la même borne de fin que `endSeconds`. Si `durationSeconds` manque, laissez sa valeur inconnue. N’écrivez pas zéro.

Les sous-titres peuvent contenir des erreurs. Ils peuvent omettre un schéma ou une action silencieuse. L’absence d’un sous-titre ne prouve pas que le point concerné manque à l’image. Si la piste manque, regardez et écoutez la vidéo. N’inventez pas de texte de sous-titres. L’Actor de transcription ne lit pas les commentaires. Il n’attribue pas d’étiquettes aux lacunes de la leçon. Il ne prouve pas qu’un apprenant n’a pas compris.

## Effectuer la vérification en 8 étapes

1. Définissez le résultat attendu de la leçon avant de collecter les commentaires. Présentez la notion en une ligne simple. Écrivez ce que l’apprenant doit être capable de faire après la leçon. Choisissez un tutoriel public. Fixez le plafond avant de lire les commentaires. Pour la première vérification, le plafond est de 2. Tenez-vous-en aux propos du spectateur. Ne supposez ni son âge, ni son niveau, ni ses motivations.
2. Vérifiez l’échantillon avant de l’interpréter. Confirmez l’identifiant de la vidéo, chaque `commentId` et le fait que `text` est exploitable. Lisez OUTPUT, notamment `commentsWritten`, `repliesWritten` et `stopReasonCounts`. Gardez l’ordre de la source et le plafond visibles dans vos notes. Signalez comme inconnu un auteur manquant ou un `publishedAt` à null. Ne transformez pas une valeur inconnue en zéro. Dans l’échantillon, 2 lignes correspondent à 2 commentaires. Elles ne correspondent pas à 2 apprenants et ne constituent pas une note de classe.
3. Choisissez un commentaire qui mentionne une tâche précise ou une difficulté de compréhension précise. Conservez le lien vers la source. Ne citez que les mots nécessaires à vos propres notes. Rédigez une interprétation simple sans ajouter de cause. Une question ne constitue pas, à elle seule, une incompréhension. Une plaisanterie, un désaccord ou une formulation répétée ne constituent pas, à eux seuls, une incompréhension. Avant d’évaluer la leçon, attribuez à la note l’étiquette `stated_confusion`, `possible_gap` ou `insufficient_context`. `stated_confusion` signifie que le commentaire mentionne une tâche ou une question précise. `possible_gap` signifie que les propos pourraient signaler un problème dans la leçon, mais que vous n’avez pas vérifié le passage. `insufficient_context` signifie qu’il manque dans le commentaire un fait dont vous avez besoin.
4. Lisez le fil public lorsque les réponses peuvent changer le sens. Ouvrez la page de la vidéo et lisez les réponses sous le commentaire concerné. Une réponse peut préciser la configuration du spectateur. Elle peut montrer que la difficulté venait d’un autre produit. Consignez ce que vous avez vérifié. Consignez ce que vous n’avez pas pu ouvrir. Le test de contrôle limité n’a enregistré aucune réponse. Ne présentez pas l’export comme un fil complet. Si vous ne trouvez pas une réponse, indiquez que le contexte des réponses est indisponible. Ne rédigez pas une réponse que vous n’avez pas lue.
5. Repérez le passage de la leçon sur la barre de lecture de la vidéo. Utilisez les sous-titres horodatés pour [repérer un intervalle possible](/fr/articles/retrouver-une-notion-dans-un-long-cours-youtube/). Lisez ensuite cet intervalle. Consignez les temps de début et de fin en secondes dans la vidéo. Consignez la notion, la phrase précédente pertinente et l’action visible. Regardez et écoutez avant de décider. Une phrase absente des sous-titres peut tout de même être clairement expliquée par un schéma. Un mot dans un sous-titre ne prouve pas que la phrase prononcée est claire ou correcte. Utilisez le temps affiché par le lecteur vidéo. N’utilisez pas l’heure de votre horloge murale.
6. Comparez le commentaire à la leçon vérifiée. Posez-vous d’abord 3 questions. La leçon a-t-elle omis l’explication ? A-t-elle déjà énoncé le point concerné ? Ou manque-t-il encore un fait nécessaire ? Enregistrez ensuite un état. Les éléments à l’appui sont le commentaire, les réponses que vous avez ouvertes et le passage que vous avez regardé. `explanation_missing` signifie que le passage n’enseigne pas le point sur lequel porte la question du spectateur. `explanation_present_question_unresolved` signifie que le passage énonce ce point et qu’aucun élément vérifié ne montre que ce spectateur ne l’a pas compris ou remarqué. Une question posée ensuite ne prouve pas qu’il est passé à côté de l’explication. N’affirmez pas que l’enseignant a échoué. Utilisez cet état, sauf si une réponse vérifiée montre que le spectateur est passé à côté de l’explication. `possible_wording_gap` signifie que la leçon montre le point concerné, mais que les mots ne le distinguent jamais de l’erreur du spectateur. `setup_mismatch` signifie que le commentaire concerne une autre configuration, un autre produit ou un autre modèle. `unresolved` signifie qu’un fait nécessaire n’a pas été vérifié et que vous ne désignez donc aucune cause. Enregistrez les éléments à l’appui à côté de l’état. Un seul commentaire exprimant une difficulté de compréhension ne peut pas montrer que tous les spectateurs ont rencontré le même problème.
7. Rédigez une seule modification, uniquement lorsque les éléments à l’appui justifient de modifier la leçon. Vous pouvez ajouter un prérequis, montrer une étape résolue, préciser l’unité, ralentir un enchaînement trop rapide ou placer un bref rappel à côté de ce passage. Un prérequis est un fait que l’apprenant doit connaître au préalable. Précisez ce qui doit devenir plus clair. Décrivez le test. Ne promettez pas que les spectateurs resteront plus longtemps. Ne promettez pas davantage de vues. Modifiez l’explication à l’endroit du passage concerné. Modifier un menu ou résumer toute la vidéo constitue une autre tâche. Si l’état est `unresolved` ou `setup_mismatch`, n’imposez pas une modification à cette leçon.
8. Enregistrez une ligne du tableau des lacunes de la leçon qu’une autre personne peut contrôler. Incluez la source du commentaire et du fil, le contexte vérifié, le temps du passage, la notion visée, l’état, la modification proposée et le contrôle de validation. Un contrôle de validation est un test qui montre que la modification a atteint son objectif ou qu’aucune modification n’était justifiée. Une autre personne doit pouvoir ouvrir les mêmes sources et suivre le raisonnement qui a conduit à la décision. Si le contexte manque, conservez la ligne à l’état `unresolved`. N’inventez pas une cause précise.

## Étudier un tableau fictif des lacunes d’une leçon

La leçon de jardinage, les commentaires, les réponses et les temps de cette section sont une fiction originale. Ils constituent un exemple pédagogique. Ce ne sont ni des données produites par un Actor, ni un résultat du produit.

La leçon fictive enseigne une compétence. L’apprenant mesure un bac et utilise une seule unité. Les segments de sous-titres inventés sont les suivants :

```json
[
  {
    "startSeconds": 20,
    "endSeconds": 28,
    "durationSeconds": 8,
    "text": "Measure the width inside the tray edges"
  },
  {
    "startSeconds": 28,
    "endSeconds": 33,
    "durationSeconds": 5,
    "text": "Use centimeters for both dimensions."
  }
]
```

Étudier un tableau fictif des lacunes d’une leçon

Vérifiez le premier intervalle par une simple addition. 20 plus 8 égale 28. Ce résultat correspond à `endSeconds`. Vérifiez le second intervalle. 28 plus 5 égale 33. Ce résultat correspond à `endSeconds`. Ces sommes confirment seulement la cohérence des temps fictifs. Elles n’évaluent pas la leçon.

Le texte des sous-titres ne mentionne pas de règle graduée. Dans cet exemple fictif, vous lisez le passage de 20–28 secondes et regardez l’image. La règle graduée commence au bord intérieur gauche. Vous le savez uniquement parce que vous avez regardé la vidéo. L’absence de mention de la règle graduée ne signifie pas que l’image est vide. Le texte des sous-titres ne prouve pas non plus que la phrase prononcée suffit.

Le rebord extérieur est la bordure externe du bac. La leçon montre les bords intérieurs. Elle ne dit jamais que le rebord extérieur est exclu.

| Commentaire | Notion | Fil vérifié | Passage de la leçon vérifié | État | Modification proposée | Contrôle de validation |
| --- | --- | --- | --- | --- | --- | --- |
| C1 sur le tutoriel fictif de jardinage. Texte du commentaire : « Dois-je mesurer à l’extérieur du bac ? » | Mesurer la largeur entre les bords intérieurs. | Vous avez ouvert le fil. La réponse indique que le spectateur a mesuré le rebord extérieur. | 20–28 secondes. Phrase prononcée : « Mesurez la largeur à l’intérieur des bords du bac. » La règle graduée commence au bord intérieur gauche. Aucune phrase prononcée ne fait la distinction avec le rebord extérieur. | `possible_wording_gap` | À 20 secondes, montrez les 2 bords, repérez le bord intérieur et dites que le rebord extérieur est exclu. | Une personne chargée de la vérification peut désigner précisément le bord de départ et le bord d’arrivée à partir du seul nouveau passage, sans consulter le fil de commentaires. |
| C2 sur le tutoriel fictif de jardinage. Texte du commentaire : « Puis-je mélanger les pouces et les centimètres ? » | Utiliser une seule unité pour les 2 dimensions. | Aucune réponse vérifiée n’indique que ce spectateur est passé à côté de la phrase sur l’unité. | 28–33 secondes. Phrase prononcée : « Utilisez des centimètres pour les 2 dimensions. » | `explanation_present_question_unresolved` | Uniquement à titre facultatif : ajoutez une indication visible de l’unité ou un bref rappel vers 28 secondes. Conservez la phrase d’origine. Ne réécrivez pas la leçon comme si la règle était absente. | Une personne chargée de la vérification peut toujours retrouver la phrase d’origine sur l’unité à 28–33 secondes. La question seule n’est pas considérée comme la preuve que le spectateur est passé à côté de l’explication. |
| C3 sur le tutoriel fictif de jardinage. Texte du commentaire : « Le bouton manque. » | Trouver un bouton. Le commentaire ne précise ni l’appareil ni la version. | Aucune réponse n’était disponible pour vérification. L’appareil et la version restent inconnus. | Indisponible. Le temps du passage est inconnu. N’en inventez pas. | `unresolved` | Aucune modification de la leçon. | La ligne reste non résolue. La personne chargée de la vérification n’ajoute ni appareil, ni version, ni cause, ni temps de passage. |
| C4 sur le tutoriel fictif de jardinage. Le commentaire pose une question sur un autre modèle de produit. | Étapes pour le modèle présenté dans cette vidéo. | Vous avez ouvert le fil. La réponse confirme que le commentaire concerne un autre modèle. | La leçon actuelle n’est pas retenue comme cause. Aucun temps de passage n’est attribué. | `setup_mismatch` | Aucune modification de cette leçon. Notez que le commentaire mentionne un autre modèle. | Une personne chargée de la vérification peut repérer l’autre modèle dans la réponse vérifiée et laisse les étapes de cette leçon inchangées. |

C1 reçoit d’abord l’étiquette `stated_confusion`, car il pose une question précise sur la mesure. Le passage indique déjà de mesurer à l’intérieur des bords du bac. L’image concorde, car la règle graduée commence au bord intérieur gauche. L’explication n’est pas absente : l’état n’est donc pas `explanation_missing`. La réponse vérifiée indique que le spectateur a utilisé le rebord extérieur. La leçon ne distingue jamais ce rebord du bord intérieur. L’état approprié est `possible_wording_gap`. La réponse ne montre pas pourquoi le spectateur a choisi le rebord. N’inventez pas de motivation. La modification consiste à établir une distinction explicite à 20 secondes. Le test utilise uniquement la nouvelle image et la nouvelle phrase.

C2 reçoit aussi d’abord l’étiquette `stated_confusion`. La phrase à 28–33 secondes donne déjà la règle : utiliser des centimètres pour les 2 dimensions. Rien dans le fil vérifié ne montre que ce spectateur est passé à côté de cette phrase. Une question posée après une phrase claire ne prouve pas que le spectateur est passé à côté. L’état est `explanation_present_question_unresolved`. Une indication de l’unité peut aider un futur spectateur à repérer la règle. Elle est facultative. Elle ne doit pas remplacer la phrase d’origine ni laisser croire que la règle manquait.

C3 reçoit l’étiquette `insufficient_context` avant la recherche d’un passage. « Le bouton manque » ne précise ni l’appareil ni la version. Aucune réponse n’ajoute ces faits. Vous ne pouvez pas choisir un temps dans la vidéo. Vous ne pouvez pas désigner une cause. Le contexte inconnu reste inconnu. L’état reste `unresolved` et le contrôle de validation interdit d’imposer une modification.

C4 commence par une question précise. Vous pouvez donc lui attribuer l’étiquette `stated_confusion` avant de vérifier le fil. La réponse vérifiée indique que le modèle n’est pas celui de cette leçon. L’état devient alors `setup_mismatch`. N’inventez pas un défaut dans le passage actuel. Ne modifiez pas cette leçon pour répondre à une question sur un autre modèle.

Comptez les lignes de cet exemple fictif. Une ligne porte l’état `possible_wording_gap`. Une ligne porte l’état `explanation_present_question_unresolved`. Une ligne porte l’état `unresolved`. Une ligne porte l’état `setup_mismatch`. Cela fait 4 lignes de commentaires. Une ligne ne prouve pas l’existence d’une personne distincte. L’exemple ne dit pas combien de personnes ont regardé la vidéo. Il ne dit pas que tous les spectateurs ont rencontré un même problème. Les temps des sous-titres servent uniquement à repérer le passage. Ils ne remplacent pas le visionnage et l’écoute.

## Prochaine action

Choisissez un commentaire qui exprime une difficulté de compréhension précise. Lisez le moment concerné de la vidéo et regardez les images, pas seulement le texte des sous-titres. Consignez une modification proposée et un test qu’une autre personne peut reproduire. Obtenez les lignes de commentaires avec l’Actor [YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper). Saisissez votre propre tutoriel dans la [Task d’analyse des commentaires vidéo](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis). L’Actor collecte uniquement les lignes de données. L’évaluation du passage vous revient toujours.

## Sources et lectures complémentaires

- [Actor YouTube Comments Scraper](https://apify.com/chronometrica/youtube-comments-scraper)
- [Task d’analyse des commentaires vidéo](https://apify.com/chronometrica/youtube-comments-scraper/examples/youtube-video-comment-analysis)
- [Task de transcription horodatée](https://apify.com/chronometrica/youtube-transcript-scraper/examples/youtube-timestamped-transcript-json)
- [Comment analyser votre audience YouTube](https://www.reddit.com/r/YouTubeCreators/comments/1tdvbvx/how_do_you_analyze_your_youtube_audience_across/)