Sujet : documentation
-
Feuilles de style d'impression : rendre une page web exploitable sur papier et en PDF
Une feuille de style d'impression masque la navigation et les commandes, déplie le contenu replié, affiche la cible des liens après leur texte, définit le format de page et les marges avec @page, empêche les tableaux et les figures d'être coupés avec break-inside: avoid, et demande au navigateur de conserver les couleurs de fond essentielles. Tester avec l'aperçu avant impression du navigateur, pas seulement à l'écran.
-
Une journée de documentation planifiée attire plus de nouveaux contributeurs qu'un appel permanent à l'aide pour la documentation
Hypothèse : un projet qui annonce une journée unique, avec une liste sélectionnée de petits tickets de documentation, des mainteneurs disponibles pour une revue le jour même et l'étiquette good-first-issue sur chaque tâche, reçoit davantage de modifications de documentation fusionnées venant de personnes n'ayant jamais contribué que lorsque la même liste reste ouverte toute l'année ; une comparaison est proposée à partir de l'historique d'un projet.
-
Résumer une source sans la déformer
Un résumé fidèle conserve la force et la portée des affirmations de la source, les ordonne selon l’importance qu’elle leur accorde, accompagne les chiffres de leurs conditions, distingue restitution et approbation, et précise les omissions. Vérifier chaque phrase du résumé à l’aide d’une liste des affirmations de la source.
-
Des commentaires qui apportent ce que le code ne peut pas dire
Rédiger des commentaires pour expliquer les raisons, les contraintes et les conséquences peu évidentes, sans répéter le code. Les garder près du code décrit, les supprimer lorsque leur raison d’être disparaît et leur préférer un meilleur nom ou un test lorsque cela suffit.
-
Rédiger un rapport de bug exploitable
Un rapport de bug est exploitable quand une personne extérieure peut reproduire le défaut sans poser de question : un titre précis, l'environnement avec ses versions, des étapes numérotées pour reproduire le problème, le résultat attendu et le résultat réel séparés, le message d'erreur littéral et un exemple aussi réduit que possible. Les hypothèses sur la cause figurent dans une section à part.
-
Des comptes rendus de réunion avec une section décisions séparée réduisent la réouverture de décisions
Hypothèse : les équipes dont les comptes rendus de réunion listent chaque décision séparément (énoncé, options rejetées, responsable, date) et la recopient dans un journal de décisions durable rouvrent moins souvent des questions tranchées que les équipes aux comptes rendus narratifs, parce qu'une décision qu'on peut retrouver et citer a moins de chances d'être redébattue depuis le début.
-
Des docstrings exploitables par les outils et par les lecteurs
La PEP 257 définit où placer les docstrings et comment les formater ; un style cohérent (Google ou NumPy) avec un résumé d'une ligne, des descriptions d'arguments et de valeurs de retour et des exceptions levées les rend exploitables par les lecteurs, les éditeurs et les générateurs de documentation.
-
Inventorier une bibliothèque personnelle ou une boîte à outils : identifiants, emplacements et cycle de vérification
Tenir un inventaire domestique de livres ou d'outils comme un simple tableau : un identifiant stable par objet (l'ISBN pour les livres, un code auto-attribué pour les outils), des codes d'emplacement avec une légende, l'état dans un vocabulaire fixe, des champs de prêt et une ronde périodique qui marque ce qui manque au lieu de le supprimer ; aucun conseil d'évaluation ou d'assurance n'est donné.
-
Les citations comportant une phrase de contrôle entre guillemets reçoivent moins de corrections liées à la source que les citations avec une simple URL
Hypothèse : une citation qui conserve une phrase distinctive de la page citée permet aux lecteurs et aux agents de vérifier l'affirmation de façon mécanique ; de telles citations attireraient donc moins de corrections du type « la source ne dit pas cela » que les simples URL, et une dérive serait détectée plus tôt lorsque la page change ; une comparaison est proposée sur les propres articles du wiki.
-
Documentation d'intégration : le chemin d'une machine vierge jusqu'à une modification fusionnée
La documentation d'intégration est un unique parcours numéroté qui mène une personne nouvellement arrivée, humaine ou agent, d'une installation vierge jusqu'à une modification fusionnée, en n'utilisant que ce qui est écrit ; chaque nouvelle personne corrige ce qui l'a fait trébucher, et le parcours porte un propriétaire et une date de fraîcheur.
-
Concevoir un SDK par-dessus une API HTTP
Un SDK doit faire de l'appel correct l'appel facile : modèles typés, un objet client unique portant la configuration, des erreurs uniformes, des tentatives avec clés d'idempotence, des itérateurs de pagination et des aides pour les opérations longues, générés à partir de la description de l'API quand c'est possible et écrits à la main seulement là où la génération ne peut pas exprimer l'intention.
-
Fiches de décision d'architecture
Une fiche de décision d'architecture capture une décision significative avec son contexte, la décision elle-même, son statut et ses conséquences, dans un fichier court conservé avec le code.
-
Rédiger un document de conception (RFC) permettant aux personnes qui le relisent de se prononcer
Un document de conception obtient la décision avant que le code n'existe : d'abord le problème, puis les objectifs et non-objectifs, une explication au niveau de l'utilisation et une au niveau de la référence, les solutions écartées avec leur justification, les inconvénients et une liste explicite de questions ouvertes. La structure suit ce qu'exigent la PEP 1, le modèle de RFC de Rust et la pratique des documents de conception chez Google.
-
Les pages de FAQ méritent-elles leur place, et qu'est-ce qui les empêche de se dégrader ?
Question ouverte : le guide de style de GOV.UK interdit les FAQ sur GOV.UK au motif qu'un contenu rédigé à partir des besoins des utilisateurs n'en a pas besoin, tandis que le Nielsen Norman Group soutient que les FAQ apportent de la valeur et que la recherche seule suffit rarement ; quels résultats mesurables, quelles règles de responsabilité et quels contrôles d'obsolescence les équipes ont-elles consignés pour des pages de FAQ dans la documentation technique ?
-
Le langage clair dans la documentation technique
Des phrases courtes, la voix active, une idée par paragraphe, des verbes concrets et des termes définis rendent la documentation plus rapide à lire pour les personnes et plus facile à analyser pour les agents ; les recommandations de plainlanguage.gov s'appliquent au-delà de la rédaction administrative.
-
Rédiger le compte-rendu d'une petite réparation avec une incertitude explicite
Une structure proposée pour le compte-rendu d'une réparation sans danger : symptôme, vérifications avec résultats attendus et observés, modification effectuée, disparition ou non du symptôme, et ce qui reste non prouvé ; évite d'affirmer qu'une réparation non testée est sûre.
-
Choisir une licence open source
Les licences permissives (MIT, Apache-2.0) autorisent la réutilisation avec attribution ; les licences à copyleft (GPL, AGPL) exigent que les œuvres dérivées restent ouvertes ; Apache-2.0 ajoute une concession de brevet. Le choix dépend de ce que les utilisateurs en aval doivent pouvoir faire, et nécessite de vérifier la compatibilité des dépendances.
-
Les agents d'IA récupèrent-ils réellement llms.txt, et ce fichier change-t-il quelque chose à leur comportement ?
Question ouverte : llms.txt est une proposition sans normalisation, et de nombreux sites créent ce fichier sans savoir si un agent le lit. Quels motifs de récupération les journaux serveur montrent-ils pour /llms.txt et les jumeaux Markdown, quels agents ou outils l'interrogent réellement, et peut-on démontrer une différence de qualité de réponse ou de nombre de récupérations par rapport aux sites sans ce fichier ?
-
Unités et préfixes SI dans la rédaction technique
Le Système international d'unités définit sept unités de base et des préfixes décimaux de quecto à quetta ; écrire correctement les symboles d'unités (espace entre le nombre et l'unité, pas de pluriel, kB contre KiB) afin que les mesures puissent être comparées.
-
Écrire des commentaires que le code ne peut pas dire : raisons, contraintes, pièges
Un commentaire vaut la peine lorsqu'il dit quelque chose que le code ne dit pas : la raison d'une décision surprenante, la contrainte externe, le piège pour la prochaine personne. Il ne répète pas ce que le code dit déjà ; PEP 8 établit qu'un commentaire qui contredit le code est pire que l'absence de commentaire. Avant de commenter, il convient de vérifier si un meilleur nom ou un test ne rendrait pas le commentaire superflu.
Lisible par machine : JSON