Écrire pour les lecteurs
Votre lecteur n'était pas là. Il connaît le domaine, pas votre projet, et il survole. Pour le choix des mots, appliquez mots-simples.
- Révision, relecture ou nettoyage d'un article, rapport ou page existant : suivez
references/passe-de-revision.md, avec les règles ci-dessous comme checklist. - Rédaction ou révision d'un article : lisez aussi
references/article.md.
Ordre
- Commencez par le résultat : ce qui s'est passé, et son ampleur. Mettez en titre la nouvelle idée ou capacité ; une comparaison n'est en tête que si elle constitue la contribution. N'ouvrez sur le problème que si une introduction est nécessaire ; jamais une introduction générique. Ne racontez pas l'historique du projet ou le journal de ce qui a été exécuté.
- Les titres énoncent l'affirmation dans un rapport (« Les forfaits moins chers vendent plus », pas « Analyse des prix ») ; un long rapport s'ouvre sur une liste numérotée de résultats.
- Les résumés et tl;drs restent à haut niveau : résultats en mots, le nombre qu'un lecteur citerait, les valeurs nulles en mots, pourquoi chacun est important. Respectez la longueur demandée. Terminez sur une affirmation simple que le lecteur retiendra.
- Les e-mails et transmissions sont une courte liste de décisions : quoi faire, à quel point chaque correction est difficile, quelle option nécessite le moins de travail manuel.
- Le texte principal se suffit à lui-même. Définissez chaque terme et comparateur là où il apparaît pour la première fois, jamais d'abord en annexe. Un long rapport se termine par un court glossaire.
Contenu
- Donnez à chaque nombre de quoi le comparer : « Précision de 25,6 % (le hasard est de 10 %) ».
- Dites l'ampleur d'un résultat, même lorsqu'il est faible.
- Montrez un exemple réel par résultat. Gardez les études de cas, les surprises et les résultats négatifs vérifiés.
- Expliquez une méthode une fois, là où elle apparaît : une ligne sur le comment ; pourquoi seulement là où le lecteur poserait autrement une question ou serait induit en erreur. Divulguez les exclusions qui définissent la population ou le dénominateur ; ne défendez pas les choix de routine.
- Pas d'avertissements de contenu ni de notes sur votre propre processus, sauf si le lieu de publication ou l'utilisateur le demande. Si un seuil ou un sous-ensemble a été choisi après avoir vu les résultats, énoncez la règle clairement, une fois.
- Énoncez une limite une fois, à côté de l'affirmation qu'elle limite, et seulement si elle modifie ce que le lecteur devrait croire. Gardez les conditions qui définissent le résultat (« en 2024 seulement »). Un quasi-échec unique sous un test de robustesse ne rétrograde pas un titre ; un renversement, si.
- Resserrez une affirmation excessive au lieu de la nuancer : gardez la partie ferme, abandonnez la partie fragile.
- Ne sabotez pas le résultat. Ne concédez rien au-delà de ce que les données montrent. N'ajoutez aucun contraste que personne n'a demandé, sauf s'il change ce que le lecteur devrait croire. Si une vérification affaiblit une histoire, proposez de corriger ou d'étendre l'analyse avant de la nuancer ou de l'abandonner ; ne modifiez pas l'analyse vous-même.
- Pas de blocs denses. Un paragraphe fait un point et peut être lu une fois, à vitesse normale. Scindez un paragraphe qui empile les résultats ou les conditions ; une série de chiffres va dans un tableau ou une liste. Les puces sont acceptables lorsque les éléments sont parallèles.
- Une seule histoire. Abandonnez les histoires secondaires. Les vérifications secondaires et les exceptions reçoivent une phrase dans le texte principal ; leur détail va en annexe.
- Comparez ce qui est comparable. Les nombres provenant de différents ensembles de données ou de personnes ont leur propre phrase ou tableau. Ne les mettez jamais côte à côte comme si l'un causait l'autre.
- Tout doit se justifier. Chaque mot, phrase, paragraphe, élément de liste, section, colonne de tableau, panneau de figure et clause de légende doit changer ce que le lecteur croit ou comment il lit quelque chose. Demandez-vous pour chacun : que perdrait le lecteur sans cela ? Si rien, coupez-le ; ne le compressez pas.
- Dites chaque chose une fois. Un nombre vit dans un tableau ou dans le texte, pas les deux ; dans le texte principal ou en annexe, pas les deux. Un résultat est énoncé complètement une fois ; le résumé, l'introduction et le synopsis ne répètent que son nombre clé.
- N'ajoutez rien qui ne soit pas dans les sources. N'inventez jamais une citation ou un résultat ; laissez un espace réservé marqué pour l'auteur.
Figures et tableaux
- Chaque panneau fait un point que le texte ne peut pas faire aussi bien. Rendez la métrique, la meilleure direction et les références évidentes.
- Des vrais noms, pas des codes ; le graphique le plus simple ; des axes titrés ; un seul jeu d'étiquettes, cohérent avec la légende et le texte. Placez une étiquette directement à côté de la série qu'elle nomme.
- Montrez tous les sous-ensembles, ou énoncez la règle qui les a choisis.
- Dans un rapport, le titre de la figure indique ce qui est montré. La légende dit comment la lire et ne répète pas les méthodes.
Avant de remettre le document
Lisez-le comme le lecteur. Pour chaque phrase : la manqueraient-ils ? Chaque nombre dit-il « comparé à quoi » ? Ensuite, exécutez mots-simples. Ne changez aucun nombre. Si quelque chose manque ou si deux nombres sont en désaccord, dites-le à l'auteur au lieu de combler le vide.