Rédiger une description de pull request claire grâce à la dictée vocale

La modification est prête, mais la description de la pull request se limite encore à « mise à jour de la documentation ». Vous savez pourquoi vous avez fait ce changement, quel détail mérite un second avis et ce que vous avez vérifié. Mettre tout cela par écrit ressemble pourtant à une nouvelle tâche.

La dictée vocale offre un point de départ simple : expliquez la modification comme à un collègue, puis transformez la transcription en un texte facile à parcourir. Le guide de GitHub sur la revue souligne aussi l’importance du contexte. Voici une méthode pour passer de votre explication orale à un brouillon utile.

1. Garder les modifications sous les yeux

Sur votre Mac, ouvrez les fichiers modifiés à côté d’un document de travail ou du formulaire de PR. Relisez les différences avant de dicter. Décrivez ce que contient cette demande, pas tout ce que vous aviez prévu de faire aujourd’hui.

Commencez par une phrase sur le résultat : « Cette modification ajoute une liste de préparation au guide de contribution. » Réservez les noms de fichiers, numéros de tickets et commandes exactes à la relecture. Les copier est souvent plus simple que les épeler.

2. Répondre à cinq questions courtes

Dictez par petits blocs, avec une pause entre chaque point :

• Qu’est-ce qui a changé ? Présentez le résultat, pas chaque opération d’édition.
• Pourquoi ce changement ? Expliquez le problème ou l’information manquante.
• Par où commencer la revue ? Indiquez le passage qui mérite de l’attention.
• Qu’ai-je vérifié ? Détaillez les contrôles terminés et leurs résultats réels.
• Que reste-t-il en suspens ? Distinguez les questions, les cas non vérifiés et les travaux hors périmètre.

Si le dépôt possède déjà un modèle de description, conservez ses rubriques. La dictée sert à remplir le brouillon, pas à remplacer le format de l’équipe.

3. Transformer l’explication en guide de relecture

Voici un exemple fictif de modification documentaire, sans rapport avec les fonctionnalités de TypeFree :

J’ai ajouté une liste de préparation parce que le guide supposait que l’environnement était déjà prêt. Commencez par la section des prérequis. J’ai ouvert les liens dans l’aperçu et ils arrivent aux bonnes pages, mais je n’ai pas suivi toute la procédure sur une machine vierge. Je voudrais un avis sur les prérequis manquants. Les commandes d’installation n’ont pas changé.

Après révision, la description pourrait devenir :

Résumé : Ajout d’une liste de préparation au guide de contribution. Les commandes d’installation restent inchangées.

Motif : Rendre explicites les préparatifs nécessaires aux nouveaux contributeurs.

Point à relire : Vérifier que la section des prérequis ne manque aucune étape.

Vérifications effectuées : Ouverture de chaque lien de la liste depuis l’aperçu de la documentation ; chaque lien mène à la page attendue.

Non vérifié : Réalisation de la procédure complète sur une machine vierge.

Il s’agit d’un exemple de rédaction, pas d’un rapport de test prêt à l’emploi. Remplacez chaque contrôle par vos propres résultats. « Je vais le tester » reste une tâche à faire, pas une validation terminée.

4. Vérifier les détails qui demandent de la précision

Copiez les noms de fichiers et les liens depuis leur source, puis assurez-vous qu’ils correspondent à cette modification. Relisez particulièrement les négations : « commandes modifiées » et « commandes non modifiées » ne décrivent pas le même périmètre.

Supprimez le récit de chaque tentative, sauf s’il explique une décision importante. La personne chargée de la revue a besoin du raisonnement derrière la solution finale, pas du compte rendu de tout votre après-midi. Laissez les questions ouvertes bien visibles.

5. Terminer par une demande précise

Remplacez « Des avis ? » par « Cette liste couvre-t-elle tous les prérequis nécessaires à une première contribution ? » Avant de partager le texte, comparez-le aux fichiers modifiés et aux résultats des vérifications.

Pour d’autres tâches de rédaction, consultez nos conseils pour rédiger des rapports de bug clairs et préparer une documentation à la voix.

TypeFree est un moyen simple de transformer la parole en texte modifiable et d’écrire plus vite. Pour votre prochaine description de PR, dictez l’explication, ajoutez les références exactes et relisez le tout avant publication.