Article original : How Google's Technical Writing Course Helped Me Become a Better Writer

Google propose un cours de rédaction technique que j'ai récemment terminé et que j'ai beaucoup apprécié. Il dure environ 4 heures et comprend des exercices pour vous tester.

Je vais brièvement expliquer ce que j'ai appris en suivant ce cours et je vais résumer les meilleurs points pour que vous puissiez avoir un bon aperçu de ce qui est couvert.

Nous allons passer en revue quelques règles de grammaire et de linguistique pour la langue anglaise, mais je vais tout expliquer dès le début pour que nous soyons tous sur la même longueur d'onde. La seule chose dont vous avez besoin pour suivre ce cours est une "petite maîtrise de l'écriture en anglais", mais "vous n'avez pas besoin d'être un bon rédacteur".

Commençons.

Introduction

Définissons quelques termes que nous allons utiliser tout au long de ce document :

• Les noms sont utilisés pour nommer quelque chose comme Mme Kay, la Tour Eiffel ou manager.
• Les pronoms sont utilisés à la place d'un nom comme je, tu, nous, eux, il ou elle.
• Les adjectifs sont utilisés pour décrire des noms comme sympathique Mme Kay, la rouilleuse Tour Eiffel ou le bon manager.
• Les verbes sont des mots d'action comme combattre, courir, taper et manger.
• Les adverbes décrivent des verbes comme combattre fortement, courir lâchement, taper agressivement et manger timidement.

Soyez clair

La clarté décrit à quel point votre point est clair dans votre écriture. Votre priorité numéro un en rédaction technique est la clarté.

Utilisation des pronoms

Chaque fois que vous utilisez des pronoms, assurez-vous qu'ils sont clairs. Il est facile de se tromper. Quelque chose comme :

Le C++ est un langage assez ancien, mais JavaScript est ancien aussi. Je l'aime vraiment.

Hein ? Vous aimez quoi ? Le C++ ou JavaScript ? Les pronoms utilisés ici n'aident pas à la clarté.

Clarifiez l'utilisation des pronoms comme suit :

Le C++ est un langage assez ancien, mais JavaScript est ancien aussi. J'aime vraiment le C++.

Généralement, lors de la relecture, si ce à quoi vous faites référence n'est pas clair, utilisez le nom au lieu du pronom. Cela ou cela sont particulièrement sujets à ce problème. Assurez-vous que chaque fois que vous utilisez ces mots, il est clair de quoi il s'agit.

Idiomes

Les idiomes sont des phrases courantes utilisées pour décrire quelque chose. Mais certains idiomes n'ont aucun sens pour un public international. Parce que les idiomes sont si spécifiques à votre région/langue, essayez de les éviter dans votre rédaction technique.

Personne ne comprend intuitivement ce que signifie tourner autour de la bouillie, mâcher le gras ou gonfler une vache. Dites simplement exactement ce que vous voulez dire, et essayez de garder vos analogies simples et sans idiomes.

Soyez concis

La concisitude mesure à quel point votre écriture est brève et clairement exprimée.

Les bons ingénieurs logiciels passent autant de temps à supprimer du code qu'à en écrire lorsqu'ils peaufinent leur travail. C'est la même chose en écriture. Un code plus court est généralement :

• Plus facile à lire pour les autres
• Plus facile à maintenir
• Les lignes de code supplémentaires ajoutent des points de défaillance supplémentaires

Tous ces points s'appliquent également à votre rédaction technique.

Parfois, polir et dire ce que vous voulez dire de manière concise prend du temps, et vous devez vraiment rédiger le document. Vous pourriez même finir par relire plusieurs fois – mais cela en vaut la peine.

Les phrases plus courtes encouragent également les lecteurs à continuer à lire. À quel point un énorme paragraphe est-il intimidant ? Cela peut parfois intimider les lecteurs, et certains lecteurs vont simplement rebondir directement hors de votre page lorsqu'ils voient des paragraphes de 1 000 mots.

Supprimer "il y a" et "il existe"

Lorsque vous relisez votre texte, "il y a" et "il existe" peuvent presque toujours être supprimés pour exprimer votre point plus brièvement.

Les deux termes sont généralement très génériques et ennuyeux pour les lecteurs. Reformulez la phrase. Voici quelques exemples :

• Il y a beaucoup de chevauchements entre le logiciel et le matériel.
• Il n'y a pas plusieurs threads en JavaScript.

J'espère que vous serez d'accord pour dire à quel point ces phrases sont maintenant meilleures :

• Le logiciel et le matériel ont beaucoup de chevauchements.
• JavaScript n'a pas plusieurs threads.

Minimiser l'utilisation des adjectifs et des adverbes

Les adjectifs et les adverbes sont beaucoup utilisés dans l'écriture descriptive et créative comme la fiction et la poésie.

L'exemple de Google est de transformer "herbe" en "herbe verdoyante et prodigue" ou de transformer "cheveux" sans vie en "cheveux soyeux et fluides".

Le problème est que les adverbes et les adjectifs sont généralement trop vaguement définis, et ils peuvent également donner à votre rédaction technique un son de marketing.

Exécuter le code en mode production fait tourner le code à une vitesse fulgurante.

Par opposition à :

Exécuter le code en mode production entraînera un gain de performance de 225 %.

J'espère que vous serez d'accord pour dire que la deuxième phrase est plus précise et quantifiable.

Utiliser des listes

Lorsque vous avez une longue phrase avec beaucoup d'éléments, vous devez la diviser en une liste. Par exemple, si vous listez les avantages d'une technologie particulière, vous pourriez dire, X est un excellent choix parce que :

• Il est léger
• Il est rapide
• Il est facile à utiliser

Bien que ce soit un exemple simple, vous voyez l'idée. Cela est maintenant beaucoup plus lisible qu'une phrase trop longue et vous ne perdrez pas vos lecteurs ou votre flux.

Utiliser la bonne liste

Si vous trouvez un bon endroit pour utiliser une liste, il est important d'utiliser la bonne liste. Vous pouvez utiliser soit une liste numérotée, comme ceci :

1. Voici ma liste numérotée
2. N'est-elle pas jolie ?

Ou vous pouvez utiliser une liste à puces, comme ceci :

• Voici ma liste à puces
• Différente, mais toujours cool

Alors, laquelle devriez-vous utiliser ?

Utilisez une liste numérotée, lorsque l'ordre compte, comme pour une recette. Essayez de commencer chaque numéro avec un verbe impératif pour renforcer les instructions étape par étape de la liste, également :

1. Allumez le four.
2. Faites cuire le gâteau.

Les listes à puces fonctionnent bien pour tout le reste.

Gardez vos listes parallèles

Maintenant que vous utilisez probablement les bonnes listes ! L'étape suivante pour vous aider à utiliser les listes à leur potentiel maximal est de les garder parallèles. Que signifie cela ?

Les éléments de votre liste doivent tous avoir :

• La même grammaire et ponctuation
• La même catégorisation logique (les éléments de la liste appartiennent raisonnablement tous ensemble)
• La même capitalisation

Prenons un mauvais exemple :

• c++
• JAVASCRIPT ?
• Rust !
• cookies aux pépites de chocolat

Toutes les règles ci-dessus ont été enfreintes. L'élément "cookies aux pépites de chocolat" n'appartient pas logiquement à la liste, la capitalisation/casse de chaque élément est différente, et la ponctuation n'est pas appliquée de manière cohérente (il n'est pas clair pourquoi "JAVASCRIPT" se termine par un "?", et "Rust" avec un "!").

Utiliser la voix active

Les phrases sont généralement composées de sujet, objet et verbe. Faisons quelques tests :

J'ai écrit une histoire.

Je suis le sujet, histoire est l'objet, et ai écrit est le verbe.

J'admire vraiment le travail de Jake.

Je suis le sujet, Jake est l'objet et admire est le verbe.

• Le sujet est celui qui fait l'action.
• L'objet est la chose à laquelle l'action est faite.
• Le verbe est ce qui est fait à l'objet par le sujet.

Tous les exemples ci-dessus utilisent la voix active parce que le sujet fait le verbe à l'objet. Alors, inversons ces exemples ci-dessus à la voix passive :

L'histoire a été écrite par moi.

Le travail de Jake a mon admiration (ou Le travail de Jake est admiré par moi)

Vous devriez utiliser la voix active parce que, en plus d'être plus puissante et directe :

• Elle est beaucoup plus facile à comprendre. Chaque fois que les gens lisent la voix passive, ils doivent faire l'effort mental de transférer la voix passive à la voix active. Donc, pour faciliter la lecture, sautez cette étape et écrivez à la voix active.
• La voix active est beaucoup plus familière au lecteur, car nous lisons des écrits à la voix active la plupart du temps.
• La voix passive oblige parfois le lecteur à deviner qui a fait quoi dans la phrase et obscurcit le sens.
• La voix active est généralement plus courte que la voix passive.

Conseils généraux pour l'écriture

Examinons comment maximiser chaque composante d'un écrit bien rédigé.

Phrases

Les développeurs sont familiers avec le fait de garder leur code à responsabilité unique. Gardez la même formule à l'esprit pour les phrases.

Exprimez une idée clairement et brièvement, avant de passer à la phrase suivante. Ne faites pas de phrases avec beaucoup de et aussi ceci et et cela aussi et et même une division supplémentaire de notre phrase finale. Si vous finissez par faire cela, divisez chaque texte après le et en sa propre phrase.

Paragraphes

Les paragraphes doivent avoir une phrase d'ouverture claire pour expliquer le point central du paragraphe.

Vous devez également répondre clairement à :

• Qu'essaiez-vous de transmettre ?
• Pourquoi est-ce important ?
• Comment le lecteur doit-il utiliser cette connaissance ?

Prenons un exemple qui fait tout ce qui précède :

La fonction garp() retourne le delta entre la moyenne et la médiane d'un ensemble de données. Beaucoup de gens croient sans réfléchir qu'une moyenne détient toujours la vérité. Cependant, une moyenne est facilement influencée par quelques points de données très grands ou très petits.

Appelez garp() pour aider à déterminer si quelques points de données très grands ou très petits influencent trop la moyenne. Une valeur relativement petite de garp() suggère que la moyenne est plus significative que lorsque la valeur de garp() est relativement élevée.

Jargon et contexte

Le jargon est la terminologie spécialisée qu'un domaine particulier utilise.

Les investisseurs peuvent parler d'un formulaire W8-BEN ou de SPAC. Mais si vous êtes en dehors de ce domaine, vous n'avez aucune idée de ce qui est discuté.

Là où c'est possible, supprimez tout le jargon et les acronymes et expliquez brièvement ce qu'est quelque chose.

Essayez de rendre votre écriture aussi simple et claire que possible, tout en donnant le crédit dû à la complexité de ce que vous discutez (ne simplifiez pas trop !). Si votre écriture est difficile ou complexe à comprendre, elle n'aidera personne.

Ne supposez pas non plus la connaissance. Si vous voulez parler de quelque chose, soit expliquez-le, soit essayez de lier à une bonne ressource à ce sujet. Certains appellent cela la Malediction de la Connaissance.

Supposez que votre lecteur en sait moins que vous, afin que les lecteurs expérimentés puissent simplement parcourir les parties qu'ils connaissent déjà, et que les débutants ne se perdent pas.

Choix des mots

L'anglais est la langue dominante pour la rédaction technique, mais l'anglais n'est pas toujours la langue maternelle du lecteur. Essayez de vous en tenir à des mots anglais simples et couramment utilisés.

Vous n'avez pas besoin de discuter de l'exubérance que vous trouvez dans les mots polysyllabiques, en exhibant votre magniloquence.

Méta-informations

Écrire une introduction

Lorsque vous écrivez quelque chose, expliquez brièvement au début ce que vous allez couvrir. Cela peut aider les gens à comprendre exactement ce que vous discutez avant de lire davantage.

Adapter votre contenu à votre public

Essayez d'adapter votre document à votre public. Lorsque vous écrivez sur dev.to, vous pouvez écrire d'une certaine manière, et lorsque vous écrivez sur freeCodeCamp News, vous pouvez écrire d'une autre manière.

Rédigez votre document pour qu'il convienne le mieux à votre public. Par exemple, si vous expliquez l'architecture de votre entreprise à un public plus large, vous devrez expliquer les choses plus en détail car il y a moins de connaissances partagées qu'avec vos collègues.

Parfois, vous n'écrivez peut-être même pas pour des personnes techniques, et vous devrez expliquer les choses de manière moins complexe pour faciliter leur compréhension.

Résumé

Faisons un bref aperçu de ce que nous avons couvert :

• Essayez d'être cohérent dans votre écriture
• Évitez les pronoms ambigus
• Préférez la voix active
• Soyez concis
• Concentrez chaque phrase sur une idée
• Utilisez des listes
• Concentrez-vous sur la suppression des mots inutiles
• N'utilisez pas d'anglais complexe ou de jargon
• Gardez les listes parallèles
• Ouvrez les paragraphes avec un aperçu de ce que vous couvrez
• Adaptez votre document à votre public
• Établissez vos points clés au début de votre écriture

Conclusion

J'espère que cet article a expliqué quelques concepts utiles que Google m'a enseignés lorsque j'ai terminé leur cours de rédaction technique.

Je vais essayer de choisir les parties pertinentes de leurs conseils au fur et à mesure qu'elles s'appliquent à l'écriture que je fais, et j'espère que cela vous aidera aussi. J'ai trouvé ici quelques règles utiles à appliquer à la documentation ou à toute rédaction technique que je produis.

Le cours auquel je fais référence tout au long de cet article peut être trouvé ici.

Je partage mes écrits sur Twitter si vous avez aimé cet article et souhaitez en voir plus.