Écrire sur un sujet technique

J’ai en tête deux types d’articles: les How to et d’autres, plus abstraits, et qui contiennent des raisonnement, soulèvent des questions, amènent une perspective. Dans la réalité il est rare qu’un article corresponde à 100% à l’un ou l’autre. Cela peut même changer d’une section à l’autre.

  1. L’article trouvera plusieurs audiences en fonction de ce qu’elles viennent y chercher, cela ne peut pas vraiment être anticipé.
  2. La lecture doit reposer d’une manière ou d’une autre sur l'intuition de la personne qui va le lire.
  3. Avoir une approche exhaustive est contreproductif puisqu’on s’adresse à des gens de parcours différents qui sont censés faire leurs propres recherches, d’où la nécessité de s’appuyer sur des mots clés faciles à rechercher. Il est impossible de s’adapter à tout le monde et dans l’autre sens, chercher à s’adapter à un seul profil de “lecteurice idéal.e” semble assez vain.
  4. Une approche ultra-minimaliste n'est pas non plus souhaitable.
  5. Pour savoir quels prérequis inclure ou non dans le texte, la question à se poser est “est-ce qu’omettre ceci va renforcer l’expérience de lecture” et non “est-ce que cette information est nécessaire”.
  6. Sur-structurer le texte en sections et sous-sections peut briser le rhythme.
  7. La conclusion de l’article doit être construite incrémentalement et non d’un seul coup à la manière d’un puzzle.
  8. Idéallement même en s’arrêtant paragraphe deux l’audience repart avec quelque chose.
  9. Quand du code est inclu éviter d’y faire référence 10 paragraphes plus loin.
  10. En règle générale le code illustre quelque chose. Donc on devrait pouvoir le lire seul et le rapprocher des concepts qu’on vient d'absorber, sans que les yeux ne fassent des aller-retours avec les lignes du dessus et du dessous. Dans le doute on peut commenter le code pour aider.
  11. Trop chercher à rassurer l’audience dans le fond ou dans la forme empêche celle-ci d’identifier les points faibles de l’article, et donc de les compenser à la lecture. Par exemple, si l’article n’a pas vocation à être structuré, rajouter une structure à posteriori avec l’objectuf de le rendre plus présentable peut poser problème. Aussi, sur-préciser un sujet qui n’est pas le coeur de l’article peut perdre l’audience, qui ne saura plus sur quoi se concentrer.
  12. Idem avec les inconsistences. Si un sujet est moins traîté qu’un autre, il est utile de laisser les choses telles quelles pour que l’audience puisse se demander pourquoi. Si une énumération contient des choses très différentes, il est utile que l’audience puisse se demander ce qu’elles font ensemble. Une phrase est plus longue qu’une autre ou encore une section très peu détaillée qui suit une section qui l’est plus.
  13. Si un article est un format “How to” il faut que sa structure reflète une série d’étape, et qu’on sache à l’avance lesquelles peuvent rater.
  14. Si on écrit pour introduire l’audience à un nouveau mode de pensée, de créativité ou de résolution de problème, il est très probable que trop de structure et trop d’étapes numérotées empêche l’audience de créer sa propre intuition puisqu’elle sera trop occupée à essayer de déchiffrer la votre.
  15. Autre exemple, une énumération qui se termine par ... ou par etc. (souvent par soucis de perfectionnisme) créera un doute inutile dans la tête de l’audience, qui se demandera si ce ... cache un élément important.
  16. Pour les définitions, il faut éviter de trop en mettre. Souvent une définition vague suffit, tant que le mot est suffisamment bien placé pour déclencher une rapide recherche. Mieux vaut que l’audience ait une conscience intuitive des concepts employés et de leur imprécision plutôt que l’illusion de croire que l’article se suffit à lui-même. Encore une fois, il est normal que l’article ait des lacunes, il ne faut pas les cacher.

Par exemple. Le manque de structure de cette page, le manque de sources et le caractère brouillon de la plupart des points vous indique clairement le niveau de confiance à accorder à cette liste: à savoir qu’il s’agit juste de l’expérience personnelle d’une personne et qu’elle n’a pas d’autre prétention. Si j’avais inclue des sources, la question se serait posée de la validité de chaque point de la liste par rapport à celles-ci. En l’absence de source, vous savez que rien ici ne fait autorité en quoique ce soit.

Exemples