Rédiger des articles de blog techniques sur des projets de codage

On peut dire qu'il est plus facile d'écrire du code que d'écrire sur code. Le code fonctionne ou ne fonctionne pas, alors que le langage naturel peut échouer ou réussir de toutes sortes de façons différentes. Mais si vous êtes un bon codeur, vous possédez la plupart des compétences nécessaires pour réussir dans cet autre type d'écriture, et les autres développeurs peuvent bénéficier du partage de vos idées.

La rédaction d'un article de blog s'apparente à l'écriture d'un code :

• Vous développez une idée et décrivez comment vous parviendrez à la concrétiser.

• Vous suivez les règles syntaxiques pour éviter les erreurs d'interprétation.

• Vous vous efforcez d'être suffisamment verbeux pour être compris tout en simplifiant autant que possible.

Lorsque vous écrivez sur il existe d'autres techniques que vous pouvez utiliser. Mais il est également utile de rester concentré sur ce que votre lecteur attend de votre article. L'un des avantages des articles de blogs techniques par rapport à d'autres types d'écrits est que les attentes du lecteur sont généralement assez évidentes.

Rédaction technique efficace

Le problème est que la rédaction technique est aride. Chaque personne a des stratégies différentes pour atténuer ce problème, mais les astuces ne peuvent pas changer ce fait central. Lire des explications abstraites sur les algorithmes et la syntaxe est une tâche difficile. Le cerveauen particulier la mémoireLe cerveau - en particulier la mémoire - fonctionne par associations, et l'information technique offre peu de points d'ancrage pour ces associations.

Cela ne s'applique pas seulement à la rédaction technique. Si vous avez déjà eu du mal à rester éveillé pendant un exposé d'une demi-heure ou une conférence, mais que vous n'avez aucun problème à vous concentrer sur un film de deux heures, vous le savez déjà. L'ennui est moins lié aux personnes qui reçoivent l'information qu'à la manière dont elle est présentée.

Pourquoi les gens lisent-ils des articles de blogs techniques ? La plupart du temps, ils veulent savoir comment accomplir une tâche ou approfondir un sujet spécifique. Votre défi consiste à répondre à ce besoin avant que leur capacité d'attention ne s'épuise.

La seule chose qui améliore presque toujours la rédaction technique, c'est qu'elle soit moins longue. Cela vaut aussi bien pour la longueur de l'article que pour la longueur des phrases. C'est même vrai pour les exemples de code que vous utilisez. La consommation d'informations techniques est déjà un défi pour notre cerveau. Vous pouvez aider les gens à comprendre votre sujet en faisant le travail de hiérarchisation des informations et en supprimant tout ce qui n'est pas crucial.

Il existe de nombreuses approches différentes pour alléger l'écriture qui vous reste. Voici quelques outils efficaces :

• Humour

• Anthropomorphisation de concepts ou de codes

• Images (GIF, pas les camemberts)

• Exemples interactifs

• Code

• Listes à puces

Certaines de ces techniques ont une incidence sur l'écriture elle-même, tandis que d'autres permettent de s'en détacher. Mais elles font toutes appel à des parties du cerveau différentes de celle qui se souvient des formules et des algorithmes. Les souvenirs sont faits de liens entre les différentes parties du cerveau, et se souvenir des choses que l'on lit au fur et à mesure est essentiel pour éviter l'épuisement mental suffisamment longtemps pour comprendre la situation dans son ensemble.

Si vous n'avez pas beaucoup écrit de textes techniques, ou si vous n'en avez pas fait beaucoup dont vous êtes satisfait, il peut être intéressant d'expérimenter d'autres façons de les alléger. La voix authentique de l'auteur est aussi importante dans un article de blog sur le code que n'importe où ailleurs. Votre voix est amplifiée par une stratégie bien planifiée qui semble naturelle.

Termes techniques

Bien sûr, c'est bien de parler de faire des blagues et d'ajouter des GIF pour pimenter votre écriture, mais à un moment ou à un autre, vous allez devoir patauger dans les eaux troubles des acronymes et de la notation hongroise.

La première façon de gérer la terminologie technique est de faire marche arrière et de s'assurer que vous avez correctement cadré votre article. Un article de blog où vous devez passer plusieurs paragraphes à expliquer chaque terme technique ne devrait probablement pas être le même que celui où vous utilisez plusieurs termes techniques dans une phrase. Si vous vous retrouvez à mélanger un grand nombre de termes techniques et que vous pensez qu'aucune personne ne peut les connaître tous, vous pouvez lier le terme à sa définition canonique plutôt que de risquer de le surexpliquer. Vous pouvez également diviser votre article en deux, avec un préquel facultatif couvrant toutes les bases que certains voudront ignorer.

Pour rendre votre texte moins aride, intégrez les termes techniques dans le flux narratif de votre article. Ainsi, au lieu de :

"getData est le nom de la fonction qui récupère les données. Sa valeur de retour est output. Elle peut ne rien renvoyer ou renvoyer un objet. Elle prend deux arguments. source est le premier argument, et filter est le second, qui est facultatif."

Vous pouvez intégrer des termes techniques au langage naturel de la manière suivante :

"En passant une donnée source dans getData comme premier argument, nous pouvons obtenir un objet output contenant nos données. Nous pouvons éventuellement ajouter un filter pour réduire les données renvoyées. S'il n'y a pas de correspondance, getData renverra simplement null."

Il peut être tentant de traiter les termes techniques avec une sorte de formalisme, mais je pense que cela rend l'écriture beaucoup plus difficile à digérer. La façon dont vous parleriez à quelqu'un avec qui vous faites de la programmation en binôme à propos du code sur lequel vous travaillez ensemble sera immédiatement plus claire.

Le rôle de la mise en forme

Le passage d'un nom narratif à un nom de variable sans être explicite sur ce que vous faites est rendu possible par les balises <code> dans le code HTML final de votre message. Elles indiquent visuellement que vous parlez d'un élément spécifique de la solution technique et peuvent également être reconnues par les technologies d'assistance. Tout autre formatage de termes techniques, comme la mise en gras du nom d'une certaine technologie ou d'un certain outil, est laissé à votre appréciation ou à celle du guide de style de votre organisation.

La manière dont vous mettez en forme les blocs de code est également importante. Au minimum, il est utile d'avoir une mise en évidence de la syntaxe. Non seulement cela facilite la compréhension visuelle du code, mais cela crée également un intérêt visuel dans votre article. Le code dans les blocs de code doit être nettoyé pour votre article. Si vos commentaires de code expliquent les mêmes choses que votre article de blog, vous pouvez les supprimer afin de présenter moins de code. Vous pouvez également supprimer toute indentation héritée du code afin qu'il ne soit pas nécessaire de faire défiler le texte horizontalement pour le lire.

Le formatage de votre article en sous-sections est utile pour organiser les informations et, selon la plateforme de blog que vous utilisez, peut fournir des raccourcis de navigation à l'intérieur de l'article. Vous pouvez également utiliser des apartés et des listes à puces pour organiser votre article. N'abusez pas de la mise en forme. La plupart des articles de blog devraient rester essentiellement sous forme de texte, même s'il s'agit de code.

Les liens vers d'autres ressources méritent un peu de stratégie. Si vous avez trouvé quelque chose d'utile et que le lien s'insère naturellement dans le flux de votre texte, il est utile d'avoir des informations supplémentaires dans le contexte. Mais vous ne devez pas ajouter tellement de liens dans votre texte qu'ils en deviennent gênants. Si vous avez beaucoup de liens à ajouter, vous pouvez toujours placer une liste en haut ou en bas de l'article. Cela présente également l'avantage de ne pas inciter les internautes à interrompre leur lecture et à aller voir ailleurs au milieu du didacticiel.

Utilisation d'images

L'utilisation d'images est assez courante dans les articles d'actualité et autres contenus dont le processus de production peut être plus long que celui d'un billet de blog. Il est également courant d'avoir au moins une image principale dans les articles techniques. Nous avons déjà abordé la question de l'utilité de ces images.

Les articles de blogs techniques peuvent également utiliser des images dans le corps de l'article. Il peut s'agir d'un soulagement visuel, comme des GIF pour casser le texte, ou d'une explication. Les seules considérations relatives aux images décoratives sont d'ordre juridique et d'accessibilité. Avec l'autorisation d'utiliser l'image et un sous-titrage attentif, tout devrait bien se passer.

Certains concepts techniques bénéficient d'une démonstration visuelle. Vous pouvez faire une capture d'écran des étapes d'un processus d'installation ou transformer le processus en un GIF. Il peut également être utile de montrer des structures de répertoire, des exemples de résultats ou une interface utilisateur que vous ne codez pas dans le message. Cependant, il est important de ne pas se reposer entièrement sur les images pour ces éléments. Vous devez toujours expliquer ce qui se trouve dans l'image ou donner suffisamment d'informations pour que les gens puissent produire la même chose localement.

Explication du code

Si vous écrivez un billet de blog sur un morceau de code, vous devez prévoir d'expliquer le code. Pointer vos lecteurs vers un repo, raconter quelques lignes et lâcher votre pseudo Twitter ne donnera probablement pas un article de blog très utile.

Si le code de votre article de blog est écrit spécifiquement dans ce but (et non dans le cadre d'un projet plus vaste), il est très utile de suivre les étapes de sa création au fur et à mesure que vous le codez. Vous disposerez ainsi d'un plan prêt à l'emploi pour votre article. Vous pouvez même littéralement prendre des notes sur vos étapes dans l'article de blog et une fois que le code est terminé, voilàvotre plan est déjà en place. Si le code n'est qu'un morceau de quelque chose d'autre, déterminez quels morceaux sont cruciaux pour le sujet de votre article, et organisez-les de manière à ce que les premières parties que vous discutez soient les dépendances de celles qui suivent.

Il s'agit bien sûr de suggestions génériques. Si vous disséquez le code de quelqu'un d'autre, ou si vous expliquez simplement quelque chose de très complexe, il peut être intéressant de commencer par le produit fini et d'adopter une approche du type "comment ont-ils fait cela ?

Une astuce qui me semble efficace consiste à rédiger la narration autour de votre code comme si les exemples de code n'existaient pas. Une autre façon de voir les choses est de faire comme si vous passiez un entretien de codage et que vous deviez exprimer les parties importantes de la solution tout en laissant les détails de l'implémentation non spécifiés. Les gens recherchent probablement dans un article de blog quelque chose qu'ils ne peuvent pas obtenir en regardant simplement le repo GitHub. getData Il y a un juste milieu entre cela et la répétition de tout le bloc de code en langage naturel.

La façon dont vous divisez votre code peut vous aider à trouver le bon équilibre entre l'explication et l'auto-documentation. Si vous pouvez diviser votre code en blocs d'une dizaine de lignes importantes (ce qui n'est pas du réchauffage ou des parenthèses fermantes), vous pouvez écrire un paragraphe de 2 à 3 phrases pour expliquer chacune d'entre elles et garder un bon rythme. Mais ce n'est pas toujours possible. Certaines fonctions sont énormes.

Si le code dont vous devez discuter est très long, envisagez de le diviser artificiellement. Je préfère le faire en laissant des commentaires comme //INSTANTIATE VARIABLES et //FETCH VALUESafin de ne pas avoir à modifier le fonctionnement du code lui-même et de ne pas risquer d'introduire un bogue à la dernière minute. Cependant, diviser un long code en modules ou en fonctions séparées fonctionne également. L'ajout d'abstractions rend votre code beaucoup plus facile à discuter, et le même avantage de réutilisation que vous obtenez dans le code lui-même est un avantage que vos articles de blog peuvent partager. Si vous écrivez à nouveau sur un sujet similaire, vous pouvez réutiliser ces éléments et peut-être même leur explication.

Pour conclure

À la fin de votre article, il est utile de confirmer le résultat attendu. Si votre lecteur a codé à chaque étape et qu'il obtient des erreurs, il se doute probablement déjà qu'il y a eu un malentendu. Mais ce n'est pas toujours le cas. Vous pourriez conclure en disant : "Maintenant, le code de votre application est prêt. Il ne vous reste plus qu'à configurer vos informations d'identification pour l'API en suivant ce tutoriel et vous serez en mesure d'exécuter l'application."

Si vous arrivez à la fin de votre article et que vous n'avez plus grand-chose à dire, c'est une bonne indication que vous avez correctement défini le champ d'application de l'article. Si vous accumulez les avertissements dans des paragraphes supplémentaires, envisagez de revenir en arrière et de corriger les éléments du code ou du message qui vous posent problème.

La dernière étape de la rédaction d'un article de blog technique est la même que pour un article non technique : l'édition. Dans le cas d'un article de blog technique, il est important de vérifier manuellement toute suggestion provenant d'un outil de relecture automatique. Si vous devez apporter des modifications à vos blocs de code, assurez-vous que le code fonctionne toujours par la suite.

Si vous souhaitez rédiger un article de blog technique sur votre travail avec les API de Vonage, nous acceptons actuellement les soumissions à notre rubrique Pleins feux sur les développeurs des développeurs.