Guide du développeur de logiciels pour la rédaction technique – La nouvelle pile

The Economist a une fois publié une annonce demandant un article de journalisme scientifique pour concourir pour une place de stage dans son équipe. La société a spécifiquement déclaré qu’elle préférerait avoir un scientifique capable d’écrire plutôt qu’un journaliste connaissant un peu la science.

Dans cet esprit, en tant que développeur de logiciels et rédacteur technique expérimenté, voici mes conseils pour rédiger des articles techniques. Je fais référence à des articles où le public est un technicien à la recherche d’un aperçu d’un produit, d’une plate-forme ou d’un outil technologique.

Habitudes et outils

Si vous avez déjà envisagé d’écrire et que vous travaillez avec la technologie, vous devez absolument vous mettre dans le cadre de la création d’articles techniques. Oui, l’écriture ne s’améliore qu’avec la pratique, mais vous n’avez pas besoin de posséder un talent d’écriture mystique. À l’époque des médias sociaux, presque tout le monde écrit. Et comme tout éditeur le sait, l’engagement n’est pas tout à fait la même chose que la littérature. Vous voudrez peut-être écrire sur une nouvelle technologie que vous venez d’utiliser ou que vous souhaitez utiliser, ou peut-être vous sentez-vous obligé de promouvoir l’une de vos technologies préférées existantes.

Si vous avez déjà pris la parole lors d’une conférence, vous comprenez qu’il s’agit d’une forme de défi barrière. Vous avez choisi de l’accepter, et après l’avoir fait une fois, il s’agit de répéter le schéma. L’écriture est similaire; Trouvez les bons outils et les bonnes sources, puis trouvez vos meilleurs moments pour obtenir des mots sur la page.

Maintenir l’habitude est plus difficile. Je suis sûr que vous connaissez quelqu’un qui a commencé un roman, mais vous connaissez probablement moins de personnes qui en ont terminé un. Heureusement, écrire environ 1000 mots est loin d’être aussi éprouvant. Vous pouvez commencer avec pas assez de mots, puis plus tard en avoir beaucoup trop. La relecture des brouillons et l’édition sont le pain et le beurre du gribouillage. Vous n’avez cette page vierge qu’une seule fois.

Il s’avère que les outils d’écriture ont leur importance. Les articles techniques mélangent des éléments tels que du texte avec des diagrammes, des images et du code. Les formater correctement – puis les exporter dans la plateforme de publication finale et vérifier que le format est toujours correct – n’est pas toujours anodin. Je pourrais écrire dans Notion, exporter dans Markdown, puis pousser dans WordPress. Si vous avez l’intention d’écrire plus d’un article, alors la fluidification de ce processus est une première nécessité.

Soyez un klaxon de voiture

L’autre Shibboleth à contourner est que si vous ne comprenez pas complètement une technologie, vous ne pouvez pas écrire à son sujet. Le but de la plupart des messages techniques est d’être un klaxon de voiture – pour annoncer que ce que vous écrivez est ici, pertinent et doit être remarqué. Vous pouvez également élucider ce qui se cache derrière la technologie, quelle était la pensée qui l’a amenée à exister et comment elle aide les gens aujourd’hui.

Bien sûr, vous voulez éviter les erreurs, mais rappelez-vous : vous êtes un klaxon de voiture, pas un livre blanc. Ré-expliquer les choses avec votre propre voix est également acceptable. En général, vous n’apprenez vraiment que des choses que vous saviez presque déjà, donc lire une explication différente de la même chose est souvent très éclairant.

Essayez d’introduire des concepts en fonction de la façon dont vous les avez rencontrés pour la première fois, et pas seulement de la façon dont Google les voit. Se mettre dans une histoire est plus qu’acceptable – en effet, cela peut être l’angle unique nécessaire.

L’introduction de termes internes ou d’idiomes, à moins qu’ils n’expriment réellement quelque chose sans autre contexte, peut rendre les choses plus difficiles à comprendre. Par exemple, Rails est décrit comme “opiniâtre” – ce qui est à la fois véridique et décrit bien à quoi s’attendre plus tard. Alors que dire que Java a une « récupération de place » n’aide pas vraiment à comprendre le langage lui-même. Montrez aux gens les marches qui mènent à la cave par tous les moyens, mais ne les descendez pas vous-même.

Un exemple

Voici un exemple d’approche. Dans le cadre d’un article, comment expliqueriez-vous les bases de SQL dans un paragraphe ?

Devriez-vous commencer par expliquer que SQL est un DSL (Domain Specific Language — et oui, à moins qu’ils ne soient évidents, vous devriez également épeler les acronymes) ? Oui, car il y a des conséquences fermes à savoir que vous pouvez tout faire avec un ensemble limité de commandes. Devriez-vous expliquer l’histoire d’Oracle ? Non, mais vous pouvez peut-être mentionner quand vous avez travaillé pour la première fois avec des données de table, pour aider à définir le contexte. Faut-il explorer les bases de données relationnelles ? Vous auriez à expliquer un peu les tables et les schémas, bien sûr. Qu’en est-il des “clés primaires et étrangères” ? Essayez d’éviter d’utiliser le terme interne lui-même au départ ; commencez par des termes tels que “fait référence à” ou un “index de”.

Sur les diagrammes et les listes de codes. De toute évidence, une table est très facile à visualiser et à dessiner (c’est pourquoi c’est un idiome si répandu) et vous pouvez trivialement afficher à la fois une requête et les tables avec lesquelles elle fonctionne :

Fruits de table

Nom	Origine
Pomme	Kazakhstan
Banane	Philippines
Cerise	Roumanie

TABLEAU pays

Nom	Continent
Kazakhstan	Europe / Asie centrale
Philippines	Asie
Roumanie	L’Europe 

Comment demander à SQL de quel continent proviennent les pommes ?

C’est un schéma faible et une requête triviale, mais Il souligne le but et l’utilisation de SQL, ainsi que des indices sur les problèmes possibles dont vous pouvez ensuite parler si nécessaire. Notez qu’une paire de tables mieux formées peut ne pas agir comme un exemple aussi simple. Cela vaut la peine de répéter ce point – un code très efficace peut être plus difficile à comprendre qu’un code plus simple utilisant des structures familières.

Aussi, au lieu de parler de clés primaires et étrangères, un diagramme est plus efficace :

Notez cependant qu’il n’y a aucune raison de limiter votre exemple aux employés, départements et bureaux ! Il est préférable, bien sûr, d’utiliser des exemples qui vous intéressent.

Concentrez-vous sur le voyage (et autres derniers conseils)

Vous utiliserez naturellement des dispositifs rhétoriques pour persuader votre auditoire de vos arguments.

Comparer des produits en tête-à-tête est acceptable pour comparer des produits correspondants, mais beaucoup moins utile pour des technologies simplement similaires. Une fois choisie, vous devez généralement utiliser une technologie du début à la fin — il est donc plus utile de montrer un parcours utilisateur complet. Les comparaisons sont utiles pour faire des pitchs d’ascenseur (“Sharknado est comme Jaws rencontre Twister”) mais à partir de là, concentrez-vous sur le voyage. Installez-le, suivez la documentation, essayez des exemples. Où as-tu trébuché ?

J’aime utiliser des sites Web qui fonctionnent comme un bac à sable pour une technologie. Par exemple, en regardant regex, il était utile de montrer des exemples immédiats avec regexr. Non seulement cela facilite l’explication – regardez mon château de sable! — cela prouve aussi que la technologie est suffisamment flexible pour s’exprimer de plusieurs manières.

Mettre les technologies dans une chronologie (naissance, croissance, mort possible) est un moyen naturel de donner un contexte, mais c’est encore plus utile pour repérer les besoins changeants et les éventuels problèmes intégrés. “Cela a commencé avant le cloud computing” indique implicitement à votre public où une nouvelle direction pourrait se situer.

La dernière chose que j’ajouterais se lit comme un conseil de longue date : n’ayez pas peur de la médiocrité initiale. Cela peut être fatal pour un pilote, mais vous ne causerez probablement pas beaucoup de consternation si votre premier article technique n’atterrit pas correctement. Essayez au moins quelques fois avant de tirer des conclusions.

Image principale via Shutterstock. Diagramme du détartreur