Gains :
- Capacité à produire des brouillons README, docstring et changelog en fonction du public cible et de la source avec l'IA
- Possibilité de séparer les couches « quoi/comment » et « pourquoi » dans la documentation et d'ajouter le « pourquoi » en tant qu'humain
- Vérifier les étapes d'installation en les exécutant personnellement et en intégrant le document au changement de code
La partie la plus souvent négligée mais la plus durable du logiciel est la documentation. Le code est lisible même après des mois ; Celui qui l’a écrit est parti, le contexte est oublié et seul reste ce qui a été écrit. Un bon README (document d'introduction qui explique ce qu'est un projet et comment l'installer et l'exécuter), des commentaires de code explicatifs et une documentation API à jour (une référence qui explique comment utiliser une interface) déterminent directement la vitesse d'une équipe. L'IA élimine une grande partie de la « fatigue d'écriture » de la documentation, mais elle présente un piège : l'IA peut déduire du code ce qu'elle fait, mais ne peut souvent pas savoir pourquoi elle est faite de cette façon.
Dans cette unité, vous apprendrez à produire un README, un commentaire de code, une docstring (bloc de commentaire écrit par fonction/classe), un document API et un journal des modifications avec l'IA ; et comment préserver humainement la partie la plus précieuse de la documentation : le « pourquoi ».
Distinction entre « Quoi » et « Pourquoi »
Il existe deux niveaux de documentation. Le premier est quoi/comment : "cette fonction trie une liste", "exécutez cette commande pour installer". Ceux-ci peuvent être extraits du code et de la structure ; L'IA excelle ici. Deuxièmement, pourquoi : "pourquoi avons-nous rendu ce service asynchrone plutôt que synchrone", "pourquoi cette valeur limite est-elle de 30 secondes", "pourquoi avons-nous choisi cette bibliothèque plutôt qu'une autre". Ceux-ci ne sont pas écrits dans le code ; C'est le produit de décisions de conception, de contraintes et de douleurs passées.
L'IA ne sait pas « pourquoi » ; Au mieux, cela constitue une supposition raisonnable, ce qui est dangereux, car une mauvaise raison est pire que pas de raison du tout. La division du travail est donc claire : l’IA rédige le « quoi/comment », vous ajoutez le « pourquoi ». Le commentaire le plus précieux est celui qui dit ce que le code ne peut pas dire.
Astuce : Ne répétez pas avec un commentaire ce que le code lui-même dit clairement (comme i = i + 1 // augmente i de un). L’IA produit parfois de tels commentaires redondants ; Éliminez-les et consacrez votre énergie aux commentaires « pourquoi ».
Étape par étape : génération de documentation avec l'IA
- Précisez le public cible. « Un développeur qui débute », « l'équipe externe qui utilisera cette API », « le futur moi » : le public donne le ton en termes de langage et de profondeur.
- Donnez la source. Ajoutez le code pertinent, le fichier README existant, un exemple d'utilisation à l'invite. Un document non sourcé est une invitation à la fabrication.
- Structure d'imposition. Sections standard pour README (Objectif, Installation, Utilisation, Configuration, Contribution), format de projet pour docstring.
- Marquez les espaces « pourquoi ». Demandez à l'IA de marquer les décisions dont elle ne connaît pas la justification comme « une note « pourquoi » est requise ici » ; Ensuite, vous remplissez ces espaces.
- Vérifier. Exécutez réellement les étapes d’installation ; essayez l'exemple de code. Un README qui ne fonctionne pas est pire que pas de README du tout.
Trois mini-étuis
Cas 1 — Intégration accélérée README. Le fichier README d'un outil open source manquait ; Les nouveaux contributeurs ont eu du mal avec l'installation pendant 2 heures en moyenne. L'équipe a donné les scripts d'installation et package.json à AI et a rédigé un README structuré, puis a exécuté les étapes elle-même sur une machine propre et a ajouté les deux dépendances manquantes. Le temps d'installation pour les contributeurs suivants a été réduit à 25 minutes en moyenne.
Cas 2 — Le piège inventé du « pourquoi ». Un développeur a demandé à l'IA un commentaire à côté d'une valeur de timeout (timeout=30). L'IA a écrit une justification raisonnable mais incorrecte « pour tolérer une latence élevée du réseau » ; la vraie raison était la limite contractuelle de 30 secondes d'un service en aval. Cette interprétation erronée a conduit un développeur ultérieur à augmenter inutilement la valeur, ce qui a conduit à un incident. Leçon : le propriétaire du code doit vérifier la justification.
Cas 3 — Le standard Docstring est devenu automatisé. Un module auxiliaire avec 40 fonctions n'avait pas de docstrings. L'IA a reçu le format du projet (style Google) et a produit des descriptions de paramètres, de retours et d'exceptions pour chaque fonction ; Le développeur les a examinés et corrigé quelques déclarations de type incorrectes. La documentation de 40 fonctions est passée d'environ une demi-journée à une heure.
Quatre modèles copiables
Brouillon README structuré :
Public cible : {{par ex. nouveau contributeur}}. Rédigez un brouillon de README basé sur les fichiers ci-dessous. Sections : objectif, fonctionnalités, exigences, installation, fonctionnement, configuration, tests, contribution. Extraire les commandes d'installation/d'exécution à partir des fichiers réels ; CONVENABLE. Marquez les endroits dont vous n'êtes pas sûr avec "[VERIFY]". Source : {{package.json / scripts / exemple de code}}
Référence Docstring/API :
Écrivez une docstring dans ces fonctions au format {{style de projet : Google/NumPy/JSDoc}} : bref résumé, paramètres (type + signification), retour, exceptions levées, 1 court exemple. Ne répétez pas CLAIREMENT ce que dit le code. Marquez les décisions de conception qui nécessitent « pourquoi » comme « [POURQUOI NÉCESSAIRE] », n'écrivez pas de justification fabriquée.{{code}}
Supprimez les espaces pour le commentaire « pourquoi » :
Dans ce code, le prochain développeur pourrait demander « pourquoi est-ce ainsi ? » (chiffres magiques, décisions inhabituelles, solutions de contournement). Donnez un commentaire SQUELETTE pour chacun, mais laissez la justification EN BLANC ; Je remplirai la justification.{{code}}
Déclaration du journal des modifications/RP :
Écrivez une {{entrée du journal des modifications / description du PR}} à partir de la différence ci-dessous. Format : ce qui a changé (dans la langue de l'utilisateur), pourquoi (problème : {{...}}), changement radical (le cas échéant), a-t-il été testé. Ajustez le jargon technique au public cible.{{diff}}
Invite faible/Invite forte
Faible : "Écrivez un fichier README pour ce projet."
Strong : "Public cible : un développeur clonant ce dépôt pour la première fois. Sur la base du package.json, docker-compose.yml et du dossier scripts/ ci-joints, rédigez un brouillon README avec les sections Objectif, Exigences, Installation, Fonctionnement, Test, Contribution. Extrayez les commandes de ces fichiers, ne les inventez pas ; marquez partout où vous n'êtes pas sûr avec [VÉRIFIER]."
La version forte donne le public, la source, la structure et la règle « faites-le, marquez-le » ; afin que le document soit basé sur des fichiers réels et que les lieux à vérifier soient clairement visibles.
Type de document
L'IA fonctionne bien
L'humain ajoute/vérifie
Installation du fichier LISEZMOI
aperçu des étapes
Exécutez les étapes et confirmez
Docstring/API
Structure, paramètre, type
Type correct et "pourquoi"
Commentaire du code
Résumé "Ce qu'il fait"
"Pourquoi est-ce" une justification
Journal des modifications/RP
première ébauche
Impact et précision
Décision architecturale (ADR)
squelette
De vraies décisions et compromis
La documentation nécessite une maintenance
L’aspect le plus dangereux d’un document est lorsqu’il semble vrai alors qu’il est faux. Lorsque le code change et que le document n’est pas mis à jour, cela induit activement le lecteur en erreur. L'IA facilite la mise à jour : lancez un diff et demandez "quelles parties du document cette modification affecte-t-elle ?" vous pouvez demander. Mais c'est le processus qui garantit l'actualité : intégrer la mise à jour de la documentation au changement de code (critère d'acceptation des PR). L’IA s’accélère ; L’équipe construit la discipline.
Attention : Ne publiez pas sans vérifier les étapes d'installation dans un README. Un document « probablement fonctionnel » peut gâcher le premier jour d'un nouveau développeur et éroder la confiance. Exécutez les étapes vous-même dans un environnement propre.
Erreurs courantes
- Obtenir le « pourquoi » adapté à l’IA. Une fausse justification est pire que l’absence de justification ; Le propriétaire du code doit écrire la raison de la conception.
- Ne pas vérifier les étapes d'installation. README qui ne fonctionne pas détruit la confiance.
- Commentaire inutile répétant le code. Cela produit du bruit, obscurcissant les véritables interprétations du « pourquoi ».
- Sans préciser le public cible. Un document dont on ne sait pas à qui il est destiné n’est d’aucune utilité ni au novice ni à l’expert.
- Séparer la mise à jour du processus. Si le document n’est pas mis à jour avec le code cela devient vite trompeur.
En résumé
L'IA allège une grande partie de la charge mécanique liée à la documentation : brouillons rapides README, docstring, référence API, journal des modifications et descriptions PR. Mais il ne peut pas connaître le « pourquoi », qui est la couche la plus précieuse, et il est dangereux de l’inventer. La division du travail est claire : l’IA produit le « quoi/comment », vous ajoutez le « pourquoi ». Spécifiez le public, fournissez des ressources, imposez une structure, marquez les emplacements appropriés et vérifiez chaque étape d'installation en l'exécutant vous-même. Faites de la documentation une partie intégrante du changement de code.
Tâche de candidature
Choisissez un module ou un petit projet dont la documentation est manquante ou obsolète. Générez d’abord un plan à partir de l’IA avec le modèle « brouillon README structuré » (ou docstring) ; Assurez-vous de donner la source et le public cible. Parcourez ensuite chaque point où l'IA a marqué [VERIFY] ou [WHY NEEDED] : exécutez réellement les étapes de configuration et remplissez les « pourquoi » de conception avec vos propres connaissances. Notez combien d'étapes doivent être corrigées et combien de « pourquoi » vous avez ajoutés.
liste de contrôle
- [ ] Dans la documentation, je distingue les couches "quoi/comment" et "pourquoi".
- [ ] Je ne laisse pas l'IA inventer le "pourquoi", je l'ajoute moi-même.
- [ ] Je donne à l'invite le public cible et les fichiers sources réels.
- [ ] Je vérifie les points [VERIFY] marqués par l'IA en les exécutant personnellement.
- [ ] J'élimine les commentaires inutiles qui répètent le code.
- [ ] J'intègre la mise à jour de la documentation dans le cadre du changement de code.