Les développeurs ne savent pas écrire ?
 |
Description
Introduction au livre
La documentation est une compétence, et l'écriture est un autre langage de programmation.
Des développeurs écrivent encore aujourd'hui.
Des messages de commit aux fichiers README, en passant par les notes de version et les blogs techniques, l'écriture est nécessaire dans de nombreux aspects de notre travail.
Ce livre est un guide pratique destiné aux développeurs qui souhaitent améliorer leurs compétences en rédaction d'articles de ce type.
Des sujets d'écriture fréquemment rencontrés comme les commentaires, les exemples de code et les documents de démarrage, à la documentation technique précise et concise, aux conseils sur les e-mails et la messagerie, et aux conseils d'utilisation de ChatGPT, nous avons compilé un contenu adapté à vos besoins spécifiques.
À mesure que l'écriture s'accumule, elle devient un document, et le document devient rapidement une compétence.
Pour les développeurs qui hésitent souvent avant d'écrire, ce livre constituera un premier pas solide vers l'amélioration de leurs compétences rédactionnelles.
Des développeurs écrivent encore aujourd'hui.
Des messages de commit aux fichiers README, en passant par les notes de version et les blogs techniques, l'écriture est nécessaire dans de nombreux aspects de notre travail.
Ce livre est un guide pratique destiné aux développeurs qui souhaitent améliorer leurs compétences en rédaction d'articles de ce type.
Des sujets d'écriture fréquemment rencontrés comme les commentaires, les exemples de code et les documents de démarrage, à la documentation technique précise et concise, aux conseils sur les e-mails et la messagerie, et aux conseils d'utilisation de ChatGPT, nous avons compilé un contenu adapté à vos besoins spécifiques.
À mesure que l'écriture s'accumule, elle devient un document, et le document devient rapidement une compétence.
Pour les développeurs qui hésitent souvent avant d'écrire, ce livre constituera un premier pas solide vers l'amélioration de leurs compétences rédactionnelles.
- Vous pouvez consulter un aperçu du contenu du livre.
Aperçu
indice
Recommandation 12
Avis du lecteur bêta n° 18
Ouverture 20
PARTIE I Les développeurs sont-ils vraiment mauvais en écriture ?
1. Les développeurs communiquent-ils par le code ? 27
2 Répétez, répétez encore 29
3 L'écriture a un but 31
4 Cessez de faire référence à la traduction 34
PARTIE II Les développeurs qui écrivent bien se distinguent dès le départ par leur code.
5 Rédiger un message de commit 41
43 raisons pour lesquelles vous devriez rédiger de bons messages d'engagement
Concevez votre engagement 46
[Pause] Anatomie d'un message de commit 47
Rédigez un titre pour le message de commit 49
Écriture du corps d'un message de commit 64
Essayez d'écrire un message de commit 68
Point d'accès au message de validation 70
6 développeurs sont 72 rédacteurs de noms
Nommer les fonctions de manière appropriée 74
Exercice 84 sur la dénomination des fonctions
7 Écrire le message d'erreur 100
Composants des messages d'erreur : notions de base
J'ai vu un message d'erreur et je ne sais pas ce qu'il signifie : 103
Je ne sais pas comment résoudre ce problème 107
J'ai suivi les instructions du message d'erreur, mais cela n'a pas fonctionné. 109
Je ne sais pas où chercher une solution 109
[Pause] Je te donne ce que j'ai, même si je n'ai ni or ni argent. 110
8 Annotations API 111
Format d'annotation API 116
Description de l'API Règles de base 118
Exercice 124
Mise en forme de la description 128
[Pause] Les descriptions des API doivent-elles être en anglais ? 130
Écriture avec la spécification OpenAPI 131
Ne vous fiez pas trop aux outils 133
[Pause] Écrivez pour votre futur vous ! 134
PARTIE III L'écriture du développeur est une affaire de relations publiques
9 Rythme 139
Veuillez lire le chapitre 142
Quelles informations dois-je inclure dans le rythme ? 143
Rédiger une lecture pratique 148
[Pause] Juger « l’information que tout le monde connaît » 153
Si possible, choisissez une jupe rouge 154
Modèles, préparés pour vous 157
10 Exemple de code 159
Où devrait se trouver l'exemple de code ? 160
161 exemples autres que le code source
Commande 168 : Création d’exemples de code source
[Pause] Masquage des informations internes dans l'exemple de code 172
Exemple de programme 173
[Pause] Les exemples cURL sont-ils également des exemples de code d'API REST ? 175
Si ça ne fonctionne pas, ce n'est pas le code 177.
11 Rapport d'invalidité 179
[Pause] Les désagréments que nous subissons lorsque le service s'interrompt 181
Qu’est-ce qu’un rapport d’invalidité ? 181
Que doit-on écrire dans un rapport d'invalidité ? 183
Qui rédige le rapport d'invalidité ? 192
Quand dois-je rédiger un rapport d'invalidité ? 193
Où dois-je rédiger un rapport d'invalidité ? 195
Notes de version 206
Notes de version ? Journal des modifications ? 207
[Pause] Votre réfutation est juste, mais pourrais-je avoir raison aussi ? 210
Jetons un coup d'œil aux notes de version 211
[Pause] Ce n'est pas fini tant que ce n'est pas fini ! Déprécié signifie « pas encore ». 213
[Pause] Et si les notes de version devenaient trop longues ? 221
[Pause] Les documents devraient-ils aussi inclure les notes de version ? 228
Jetons un coup d'œil au journal des modifications 229
[Pause] S'il n'y a pas d'information pertinente, indiquez-le. 234
13 Document de démarrage 236
Introduction à la prise en main : inscription et installation de 238
Premiers pas : Exécution des fonctions de base 240
Fin du commencement 243
Exercice de recherche de problèmes 246
14 blogs technologiques 253
Quel est votre objectif ? 254
Blog, Cadre de base 257
Blog : Que dois-je écrire ? 268
[Faites une pause] Essayez de vendre par les mots 270
276 éléments à prendre en compte lors de la rédaction d'un blog
[Pause] Écriture digeste 277
Commençons à bloguer 283
Bloguer, c'est difficile, non ? 289
PARTIE IV Il existe une technique pour la rédaction technique.
15 Précision 295
Utilisation de la terminologie correcte 298
[Pause] 305 : Présentation pratique des documents techniques
Phrases impératives et déclaratives 307
Quand peut-on exprimer à la fois des phrases impératives et déclaratives ? 316
[Faites une pause] Faites une pause dès que vous le pouvez ! 317
Reflétant les dernières informations 317
16 Concision 326
Écrire entre parenthèses 328
Liste et tableau 335
[Pause] Un document rédigé uniquement sous forme de liste de points est-il vraiment facile à lire ? 341
[Pause] Fusion des cellules : pénible mais inévitable 345
Diagramme 348
17 Complétude 363
Rédiger une introduction 364
[Pause] Imprimez le glossaire dans une courte fenêtre contextuelle 371
[Pause] Le contenu et le but sont plus importants que la forme et la technique 374
Écrire et effacer 374
Écriture en coréen 387
[Pause] Vous voyez de quoi je parle ? 389
[Faites une pause] On peut le faire en coréen, dans notre propre langue aussi 396
ANNEXE Messages et outils d'IA commencent tous deux par l'écriture.
Écrire un e-mail ou un message 403
Écrivez un courriel ou laissez un message 404
Direct et Répondre 406
Signaler un problème 408
B Utilisation de ChatGPT 411
« Aidez-moi » au lieu de « Faites-le vous-même » 411
Commentaires sur l'API d'écriture : 413
Règles de vérification 419
Source de l'illustration 426
Avis du lecteur bêta n° 18
Ouverture 20
PARTIE I Les développeurs sont-ils vraiment mauvais en écriture ?
1. Les développeurs communiquent-ils par le code ? 27
2 Répétez, répétez encore 29
3 L'écriture a un but 31
4 Cessez de faire référence à la traduction 34
PARTIE II Les développeurs qui écrivent bien se distinguent dès le départ par leur code.
5 Rédiger un message de commit 41
43 raisons pour lesquelles vous devriez rédiger de bons messages d'engagement
Concevez votre engagement 46
[Pause] Anatomie d'un message de commit 47
Rédigez un titre pour le message de commit 49
Écriture du corps d'un message de commit 64
Essayez d'écrire un message de commit 68
Point d'accès au message de validation 70
6 développeurs sont 72 rédacteurs de noms
Nommer les fonctions de manière appropriée 74
Exercice 84 sur la dénomination des fonctions
7 Écrire le message d'erreur 100
Composants des messages d'erreur : notions de base
J'ai vu un message d'erreur et je ne sais pas ce qu'il signifie : 103
Je ne sais pas comment résoudre ce problème 107
J'ai suivi les instructions du message d'erreur, mais cela n'a pas fonctionné. 109
Je ne sais pas où chercher une solution 109
[Pause] Je te donne ce que j'ai, même si je n'ai ni or ni argent. 110
8 Annotations API 111
Format d'annotation API 116
Description de l'API Règles de base 118
Exercice 124
Mise en forme de la description 128
[Pause] Les descriptions des API doivent-elles être en anglais ? 130
Écriture avec la spécification OpenAPI 131
Ne vous fiez pas trop aux outils 133
[Pause] Écrivez pour votre futur vous ! 134
PARTIE III L'écriture du développeur est une affaire de relations publiques
9 Rythme 139
Veuillez lire le chapitre 142
Quelles informations dois-je inclure dans le rythme ? 143
Rédiger une lecture pratique 148
[Pause] Juger « l’information que tout le monde connaît » 153
Si possible, choisissez une jupe rouge 154
Modèles, préparés pour vous 157
10 Exemple de code 159
Où devrait se trouver l'exemple de code ? 160
161 exemples autres que le code source
Commande 168 : Création d’exemples de code source
[Pause] Masquage des informations internes dans l'exemple de code 172
Exemple de programme 173
[Pause] Les exemples cURL sont-ils également des exemples de code d'API REST ? 175
Si ça ne fonctionne pas, ce n'est pas le code 177.
11 Rapport d'invalidité 179
[Pause] Les désagréments que nous subissons lorsque le service s'interrompt 181
Qu’est-ce qu’un rapport d’invalidité ? 181
Que doit-on écrire dans un rapport d'invalidité ? 183
Qui rédige le rapport d'invalidité ? 192
Quand dois-je rédiger un rapport d'invalidité ? 193
Où dois-je rédiger un rapport d'invalidité ? 195
Notes de version 206
Notes de version ? Journal des modifications ? 207
[Pause] Votre réfutation est juste, mais pourrais-je avoir raison aussi ? 210
Jetons un coup d'œil aux notes de version 211
[Pause] Ce n'est pas fini tant que ce n'est pas fini ! Déprécié signifie « pas encore ». 213
[Pause] Et si les notes de version devenaient trop longues ? 221
[Pause] Les documents devraient-ils aussi inclure les notes de version ? 228
Jetons un coup d'œil au journal des modifications 229
[Pause] S'il n'y a pas d'information pertinente, indiquez-le. 234
13 Document de démarrage 236
Introduction à la prise en main : inscription et installation de 238
Premiers pas : Exécution des fonctions de base 240
Fin du commencement 243
Exercice de recherche de problèmes 246
14 blogs technologiques 253
Quel est votre objectif ? 254
Blog, Cadre de base 257
Blog : Que dois-je écrire ? 268
[Faites une pause] Essayez de vendre par les mots 270
276 éléments à prendre en compte lors de la rédaction d'un blog
[Pause] Écriture digeste 277
Commençons à bloguer 283
Bloguer, c'est difficile, non ? 289
PARTIE IV Il existe une technique pour la rédaction technique.
15 Précision 295
Utilisation de la terminologie correcte 298
[Pause] 305 : Présentation pratique des documents techniques
Phrases impératives et déclaratives 307
Quand peut-on exprimer à la fois des phrases impératives et déclaratives ? 316
[Faites une pause] Faites une pause dès que vous le pouvez ! 317
Reflétant les dernières informations 317
16 Concision 326
Écrire entre parenthèses 328
Liste et tableau 335
[Pause] Un document rédigé uniquement sous forme de liste de points est-il vraiment facile à lire ? 341
[Pause] Fusion des cellules : pénible mais inévitable 345
Diagramme 348
17 Complétude 363
Rédiger une introduction 364
[Pause] Imprimez le glossaire dans une courte fenêtre contextuelle 371
[Pause] Le contenu et le but sont plus importants que la forme et la technique 374
Écrire et effacer 374
Écriture en coréen 387
[Pause] Vous voyez de quoi je parle ? 389
[Faites une pause] On peut le faire en coréen, dans notre propre langue aussi 396
ANNEXE Messages et outils d'IA commencent tous deux par l'écriture.
Écrire un e-mail ou un message 403
Écrivez un courriel ou laissez un message 404
Direct et Répondre 406
Signaler un problème 408
B Utilisation de ChatGPT 411
« Aidez-moi » au lieu de « Faites-le vous-même » 411
Commentaires sur l'API d'écriture : 413
Règles de vérification 419
Source de l'illustration 426
Image détaillée
Dans le livre
Une plage de commits bien structurée facilitera non seulement la rédaction d'un titre, mais sera également utile en cas de restauration nécessaire.
Imaginons que le code qui corrigeait un bug en introduise un nouveau.
La restauration du code peut supprimer celui qui a causé le problème, mais elle supprimera également le code qui a modifié le texte de l'interface utilisateur.
Si vous aviez validé séparément le code qui corrige le bug et le code qui corrige les chaînes de caractères de l'interface utilisateur, vous pourriez conserver la version qui corrige les chaînes de caractères de l'interface utilisateur.
--- p.46
Si vous avez du mal à trouver un nom de fonction, essayez de changer l'ordre de votre travail et d'écrire d'abord le titre du message que vous souhaitez valider.
Vous examinez le titre du message, vous en déduisez une liste des fonctions à exécuter, puis vous examinez cette liste et vous en déduisez les noms des fonctions.
S'il s'agit d'une fonction simple, vous pouvez probablement la deviner rien qu'en regardant le titre.
--- p.74
Les noms des erreurs sont abrégés, tels que INVALID_ARGUMENT, TEMPORARILY_UNAVAILABLE, Duplicated Id ou Does not exist.
Une description d'erreur contient une phrase expliquant pourquoi l'erreur s'est produite.
Le message d'erreur doit contenir la cause de l'erreur dans une phrase afin que l'utilisateur puisse comprendre précisément la situation.
--- pp.104-105
S'il existe un exemple de code, la plupart des développeurs regarderont d'abord le code, puis liront l'explication.
De ce fait, on croit à tort que tout ira bien si l'on se contente d'un exemple de code.
Certaines personnes se contentent de publier un tas de code sans aucune explication, en disant : « Pourquoi s'embêter à écrire quelque chose quand on peut le comprendre en regardant le code de toute façon ? »
(...) Un exemple de code bien écrit ne consiste pas simplement à coller l'intégralité du code source d'un programme d'exemple complet.
Un bon exemple de code est celui qui explique clairement par écrit comment utiliser une fonction spécifique, puis qui extrait et inclut uniquement le code relatif à cette fonction.
Il n'est pas nécessaire que ce soit le code complet, car l'objectif est d'expliquer la fonctionnalité.
Le code complet et fonctionnel peut être présenté en une seule fois une fois l'explication terminée, ou fourni dans un dépôt séparé.
--- p.160
Veuillez décrire le handicap en deux parties : un résumé et une description détaillée.
Décrivez brièvement le problème en deux ou trois phrases, en veillant à ce qu'il soit facile à comprendre pour les lecteurs qui ne sont pas forcément des développeurs.
Plutôt que de simplement indiquer qu'un problème est survenu avec un produit ou un service, précisez clairement le désagrément causé à l'utilisateur.
Par exemple, au lieu de terminer par « Le serveur est surchargé en raison d'une augmentation du trafic », écrivez « Les utilisateurs du service ○○ ne peuvent pas se connecter en raison d'une augmentation du trafic et d'une surcharge du serveur. »
--- p.184
Que faire si vous ne pouvez pas rédiger une introduction sans introduire de nouveaux termes ou abréviations ? Dans ce cas, il est préférable d’utiliser les termes tels quels, mais de les relier plutôt que de les expliquer en détail dans l’introduction.
Par exemple, si vous devez absolument utiliser le terme PSS dans l'introduction, insérez un lien vers une autre page qui explique ce terme (soit un site externe, soit un glossaire dans le document actuel, soit un article connexe).
Cela vous permet d'introduire de nouveaux termes sans gaspiller d'espace introductif.
Imaginons que le code qui corrigeait un bug en introduise un nouveau.
La restauration du code peut supprimer celui qui a causé le problème, mais elle supprimera également le code qui a modifié le texte de l'interface utilisateur.
Si vous aviez validé séparément le code qui corrige le bug et le code qui corrige les chaînes de caractères de l'interface utilisateur, vous pourriez conserver la version qui corrige les chaînes de caractères de l'interface utilisateur.
--- p.46
Si vous avez du mal à trouver un nom de fonction, essayez de changer l'ordre de votre travail et d'écrire d'abord le titre du message que vous souhaitez valider.
Vous examinez le titre du message, vous en déduisez une liste des fonctions à exécuter, puis vous examinez cette liste et vous en déduisez les noms des fonctions.
S'il s'agit d'une fonction simple, vous pouvez probablement la deviner rien qu'en regardant le titre.
--- p.74
Les noms des erreurs sont abrégés, tels que INVALID_ARGUMENT, TEMPORARILY_UNAVAILABLE, Duplicated Id ou Does not exist.
Une description d'erreur contient une phrase expliquant pourquoi l'erreur s'est produite.
Le message d'erreur doit contenir la cause de l'erreur dans une phrase afin que l'utilisateur puisse comprendre précisément la situation.
--- pp.104-105
S'il existe un exemple de code, la plupart des développeurs regarderont d'abord le code, puis liront l'explication.
De ce fait, on croit à tort que tout ira bien si l'on se contente d'un exemple de code.
Certaines personnes se contentent de publier un tas de code sans aucune explication, en disant : « Pourquoi s'embêter à écrire quelque chose quand on peut le comprendre en regardant le code de toute façon ? »
(...) Un exemple de code bien écrit ne consiste pas simplement à coller l'intégralité du code source d'un programme d'exemple complet.
Un bon exemple de code est celui qui explique clairement par écrit comment utiliser une fonction spécifique, puis qui extrait et inclut uniquement le code relatif à cette fonction.
Il n'est pas nécessaire que ce soit le code complet, car l'objectif est d'expliquer la fonctionnalité.
Le code complet et fonctionnel peut être présenté en une seule fois une fois l'explication terminée, ou fourni dans un dépôt séparé.
--- p.160
Veuillez décrire le handicap en deux parties : un résumé et une description détaillée.
Décrivez brièvement le problème en deux ou trois phrases, en veillant à ce qu'il soit facile à comprendre pour les lecteurs qui ne sont pas forcément des développeurs.
Plutôt que de simplement indiquer qu'un problème est survenu avec un produit ou un service, précisez clairement le désagrément causé à l'utilisateur.
Par exemple, au lieu de terminer par « Le serveur est surchargé en raison d'une augmentation du trafic », écrivez « Les utilisateurs du service ○○ ne peuvent pas se connecter en raison d'une augmentation du trafic et d'une surcharge du serveur. »
--- p.184
Que faire si vous ne pouvez pas rédiger une introduction sans introduire de nouveaux termes ou abréviations ? Dans ce cas, il est préférable d’utiliser les termes tels quels, mais de les relier plutôt que de les expliquer en détail dans l’introduction.
Par exemple, si vous devez absolument utiliser le terme PSS dans l'introduction, insérez un lien vers une autre page qui explique ce terme (soit un site externe, soit un glossaire dans le document actuel, soit un article connexe).
Cela vous permet d'introduire de nouveaux termes sans gaspiller d'espace introductif.
--- p.370
Avis de l'éditeur
La documentation est aussi importante que le code, et nous allons maintenant vous apprendre à la rédiger.
« Les développeurs ne savent pas écrire ? »
Si les développeurs sont si mauvais en écriture, qui écrit tous ces articles techniques et ces billets de blog ? Ce sont tous des développeurs qui les écrivent.
J'écris des messages de commit, je nomme des variables, j'écris des fichiers README et je réponds aux messages Slack tous les jours, j'écris constamment.
Pourtant, de nombreux développeurs trouvent l'écriture difficile.
Parce que je n'ai jamais appris quoi écrire ni comment l'écrire.
Ce livre apporte des réponses pratiques à cette confusion.
Ce guide, avec des exemples pratiques, explique des stratégies d'écriture pratiques que vous pouvez immédiatement appliquer dans votre travail : comment rédiger des messages de commit clairs et concis, les principes pour des noms de variables et de fonctions plus clairs, comment affiner les messages d'erreur et les commentaires du point de vue de l'utilisateur, comment structurer facilement les fichiers README et les documents de démarrage, et même des conseils pour améliorer la clarté des explications dans les blogs techniques.
Ce guide complet couvre la rédaction technique essentielle aux développeurs d'aujourd'hui, depuis les écrits collaboratifs essentiels comme les e-mails et les messages Slack jusqu'aux invites pour poser et expliquer des questions à ChatGPT.
Les développeurs ne savent pas écrire ? Non.
Grâce à ce livre, même les développeurs peuvent devenir de bons écrivains.
Contenu principal
● Comment rédiger clairement les messages de commit, les messages d'erreur et les commentaires
● Principes de dénomination pour créer de bons noms de variables et de fonctions
● Comment structurer concrètement les fichiers Lisez-moi, les notes de version et les guides de démarrage
● Comment améliorer vos explications grâce à des blogs techniques et des exemples de code
● Trois techniques pour rédiger une documentation technique précise et concise
● Conseils pour rédiger de bons courriels et messages et utiliser ChatGPT
« Les développeurs ne savent pas écrire ? »
Si les développeurs sont si mauvais en écriture, qui écrit tous ces articles techniques et ces billets de blog ? Ce sont tous des développeurs qui les écrivent.
J'écris des messages de commit, je nomme des variables, j'écris des fichiers README et je réponds aux messages Slack tous les jours, j'écris constamment.
Pourtant, de nombreux développeurs trouvent l'écriture difficile.
Parce que je n'ai jamais appris quoi écrire ni comment l'écrire.
Ce livre apporte des réponses pratiques à cette confusion.
Ce guide, avec des exemples pratiques, explique des stratégies d'écriture pratiques que vous pouvez immédiatement appliquer dans votre travail : comment rédiger des messages de commit clairs et concis, les principes pour des noms de variables et de fonctions plus clairs, comment affiner les messages d'erreur et les commentaires du point de vue de l'utilisateur, comment structurer facilement les fichiers README et les documents de démarrage, et même des conseils pour améliorer la clarté des explications dans les blogs techniques.
Ce guide complet couvre la rédaction technique essentielle aux développeurs d'aujourd'hui, depuis les écrits collaboratifs essentiels comme les e-mails et les messages Slack jusqu'aux invites pour poser et expliquer des questions à ChatGPT.
Les développeurs ne savent pas écrire ? Non.
Grâce à ce livre, même les développeurs peuvent devenir de bons écrivains.
Contenu principal
● Comment rédiger clairement les messages de commit, les messages d'erreur et les commentaires
● Principes de dénomination pour créer de bons noms de variables et de fonctions
● Comment structurer concrètement les fichiers Lisez-moi, les notes de version et les guides de démarrage
● Comment améliorer vos explications grâce à des blogs techniques et des exemples de code
● Trois techniques pour rédiger une documentation technique précise et concise
● Conseils pour rédiger de bons courriels et messages et utiliser ChatGPT
SPÉCIFICATIONS DES PRODUITS
- Date d'émission : 20 novembre 2025
- Nombre de pages, poids, dimensions : 428 pages | 170 × 225 × 20 mm
- ISBN13 : 9791194587637
Vous aimerez peut-être aussi
카테고리
Langue coréenne
Langue coréenne
![ELLE 엘르 스페셜 에디션 A형 : 12월 [2025]](http://librairie.coreenne.fr/cdn/shop/files/b8e27a3de6c9538896439686c6b0e8fb.jpg?v=1766436872&width=3840)
