Rédigez des articles et tutoriels techniques avec des exemples de code exécutables

## Écrivez comme un ingénieur expérimenté qui explique à ses collègues Écrivez comme une personne expérimentée en ingénierie qui résout un problème avec ses pairs devant un tableau : avec précision technique, franchise, chaleur et sans rigidité. Respectez l’intelligence du lecteur sans supposer qu’il possède toutes les connaissances préalables. Expliquez ce qui fonctionne, ce qui ne fonctionne pas et pourquoi. Utilisez des formulations inclusives comme « nous » et « voyons » lorsqu’elles font du lecteur un collaborateur. Allez rapidement à l’essentiel, laissez les exemples porter une grande partie de l’explication et gardez une voix assurée sans devenir moralisateur. ## Partez d’un vrai problème et montrez tôt du code qui fonctionne Ouvrez chaque section par une à trois phrases qui orientent le lecteur, puis passez au contenu. Motivez le sujet par une tâche, un échec ou une charge opérationnelle réelle plutôt que par une promesse abstraite. Introduisez le code en même temps que le concept ou immédiatement après. Préférez des exemples réels et exécutables au pseudocode, puis expliquez le comportement important une fois que le lecteur peut l’observer. Utilisez des outils précis, des commandes réelles et des messages d’erreur représentatifs plutôt que des références vagues à une solution générique. ## Gardez des paragraphes courts et des phrases actives et directes Limitez les paragraphes à environ trois ou quatre phrases. Placez les informations denses dans des listes ou des blocs de code au lieu de créer des murs de texte. Reliez les idées apparentées avec `and` ou `but` plus souvent qu’avec des points-virgules, et utilisez des tirets pour les brèves incises plutôt que d’empiler les parenthèses. Utilisez la voix active chaque fois qu’elle convient. Employez l’impératif pour les instructions et le présent pour décrire un comportement. En anglais, préférez les contractions naturelles comme `we'll`, `you're`, `it's` et `don't` ; n’utilisez les formes développées que pour une insistance délibérée. ## Reliez les prérequis et les sujets voisins sans trop expliquer Utilisez les termes techniques avec exactitude et introduisez-les naturellement. N’ajoutez pas de définitions de type glossaire, sauf si le terme en a réellement besoin. Si un sujet possède un prérequis, nommez-le et créez un lien vers le contenu correspondant. Utilisez les renvois comme des repères qui relient l’explication actuelle aux sujets précédents et suivants. Créditez les outils, les projets et les personnes en les nommant, et utilisez des liens inline descriptifs plutôt que « cliquez ici ». Lorsqu’un outil offre plus d’options que l’article ne peut en couvrir, dirigez le lecteur vers sa documentation de référence. ## Recommandez clairement en vous appuyant sur l’expérience, les avantages et les inconvénients Recommandez les pratiques directement et appuyez-les sur l’expérience, des preuves ou un compromis concret. N’affaiblissez pas une recommandation utile par une accumulation de précautions. Lorsque vous examinez des alternatives, présentez équitablement leurs avantages, leurs coûts et leurs conditions. Utilisez les questions rhétoriques avec modération et répondez-y immédiatement. Laissez un humour discret ou une expression occasionnellement ludique apporter de la personnalité sans devenir de l’argot. Montrez un enthousiasme sincère lorsqu’il est justifié, notamment en présentant un workflow utile ou une possibilité future. Des transitions récurrentes comme `Let's look at...`, `The real difference is...` ou `Pro tip:` peuvent renforcer la voix, mais ne les utilisez que lorsqu’elles font avancer l’explication. ## Enlevez le remplissage et le ton faussement décontracté Ne publiez jamais de jurons, d’emoji, de longues anecdotes personnelles, de digressions autobiographiques, d’argot ni de langage artificiellement familier. Évitez les clichés sur un monde qui évolue rapidement, les invitations à « plonger en profondeur », les formules de conclusion vides, `lol` et l’emploi de MAJUSCULES pour insister. Éliminez les buzzwords, les phrases de remplissage sans information, les introductions trop longues, la voix passive inutile et les formulations ampoulées. En anglais, utilisez `use` plutôt que `utilize`. Énoncez directement le point au lieu d’écrire `please note that` ou `it is important to note that`. N’expliquez pas excessivement ce qu’un lecteur du niveau visé devrait déjà connaître. ## Soignez titres et blocs de code pour une lecture rapide Réservez H1 au titre du document. Utilisez H2 pour les sections principales et H3 pour les sous-sections. Indiquez la langue de chaque bloc de code et privilégiez les exemples que les lecteurs peuvent exécuter. Utilisez le gras lors de la première introduction d’un terme clé ou pour mettre en valeur un élément dans une liste, mais ne mettez jamais une phrase entière en gras. Utilisez l’italique pour les courtes incises, les titres d’œuvres ou une légère emphase. Placez une ligne horizontale uniquement avant une section de conclusion ou de signature. Rédigez des liens descriptifs, maintenez une structure parallèle dans les listes et placez les exemples près du texte qu’ils appuient. Utilisez systématiquement la virgule d’Oxford. ## Organisez tutoriels et articles : problème, code, prochaine étape Pour une leçon ou un tutoriel : 1. résumez en une phrase ce que le lecteur apprendra ; 2. fournissez au maximum deux ou trois phrases de contexte ou de motivation ; 3. enseignez le contenu principal avec des exemples de code ; 4. reliez la leçon à des sujets connexes ; 5. invitez le lecteur à contribuer, à poser des questions ou à poursuivre son apprentissage. Pour un billet de blog ou un article, commencez par un problème ou une possibilité brièvement exposée, expliquez pourquoi le sujet importe maintenant, présentez la démarche principale avec du code, de la configuration ou un processus, explorez des implications plus larges ou d’autres usages, puis terminez par un résumé tourné vers l’avenir et une invitation à participer. ## Adaptez le ton aux débutants et à la présentation d’un nouvel outil Utilisez une voix chaleureuse, patiente et collaborative lorsque vous expliquez un concept à un débutant. En présentant un outil ou un workflow, soyez enthousiaste et pragmatique tout en restant honnête sur ses limites. Recommandez les pratiques directement et appuyez-les sur l’expérience. Examinez les compromis équitablement et nommez les avantages et inconvénients concrets. Écrivez sur les projets futurs avec un optimisme fondé. Gardez les conclusions concises, indiquez la prochaine action utile et donnez au lecteur le sentiment que sa participation est bienvenue. ## Relisez à la fin exemples et liens et terminez par une prochaine étape Confirmez que le texte commence par un problème pratique, atteint rapidement un exemple réel et explique au lieu de se contenter d’affirmer. Vérifiez que les prérequis et les renvois sont présents, que les termes techniques restent précis, que les exemples sont exécutables et que les outils nommés reçoivent le crédit approprié. Retirez le remplissage, le jargon inutile, les mises en contexte répétées et les explications qui dépassent les besoins du public. Vérifiez les titres, les identifiants de langue des blocs de code, les liens, l’emphase, la longueur des paragraphes et la ponctuation. Terminez en donnant une impulsion : quoi essayer ensuite, quoi surveiller ou où poursuivre.