Article original : Technical Writing for Beginners – An A-Z Guide to Tech Blogging Basics

Si vous aimez écrire et la technologie, la rédaction technique pourrait être une carrière adaptée pour vous. C'est aussi quelque chose d'autre que vous pouvez faire si vous aimez la tech mais ne souhaitez pas vraiment coder toute la journée.

La rédaction technique pourrait aussi être pour vous si vous aimez apprendre en enseignant aux autres, contribuer à des projets open source et enseigner aux autres comment faire de même, ou simplement appréciez expliquer des concepts complexes de manière simple à travers votre écriture.

Plongeons dans les fondamentaux et apprenons ce que vous devez savoir et considérer lorsque vous commencez avec la rédaction technique.

Table des matières

Dans cet article, nous allons examiner :

Qu'est-ce que la rédaction technique ?

La rédaction technique est l'art de fournir des instructions détaillées pour aider les utilisateurs à comprendre une compétence ou un produit spécifique.

Et un rédacteur technique est quelqu'un qui écrit ces instructions, autrement connues sous le nom de documentation technique ou de tutoriels. Cela peut inclure des manuels utilisateur, des articles de support en ligne, ou des documents internes pour les codeurs/développeurs d'API.

Un rédacteur technique communique de manière à présenter des informations techniques de sorte que le lecteur puisse utiliser ces informations pour un but précis.

Avantages de la rédaction technique

Les rédacteurs techniques sont des apprenants toute leur vie. Puisque le travail implique de communiquer des concepts complexes en termes simples et directs, vous devez être bien versé dans le domaine sur lequel vous écrivez. Ou être prêt à apprendre à ce sujet.

C'est génial, car avec chaque nouveau document technique que vous recherchez et écrivez, vous deviendrez un expert sur ce sujet.

La rédaction technique vous donne également un meilleur sens de l'empathie utilisateur. Elle vous aide à prêter plus attention à ce que les lecteurs ou utilisateurs d'un produit ressentent plutôt qu'à ce que vous pensez.

Vous pouvez également gagner de l'argent en tant que rédacteur technique en contribuant à des organisations. Voici certaines organisations qui vous paient pour écrire pour elles, comme Smashing Magazine, AuthO, Twilio, et Stack Overflow.

En plus de tout cela, vous pouvez contribuer à des communautés Open Source et participer à des programmes open source payants comme Google Season of Docs et Outreachy.

Vous pouvez également prendre la rédaction technique comme profession à temps plein – de nombreuses entreprises ont besoin de quelqu'un avec ces compétences.

Compétences nécessaires pour être rédacteur technique

Comprendre l'utilisation de l'anglais correct

Avant de considérer l'écriture, il est nécessaire d'avoir une bonne maîtrise de l'anglais, de ses temps, de son orthographe et de sa grammaire de base. Vos lecteurs ne veulent pas lire un article truffé de grammaire incorrecte et de mauvais choix de mots.

Savoir expliquer les choses clairement et simplement

Savoir implémenter une fonctionnalité ne signifie pas nécessairement que vous pouvez communiquer clairement le processus aux autres.

Pour être un bon enseignant, vous devez être empathique, avec la capacité d'enseigner ou de décrire des termes de manière adaptée à votre public cible.

Si vous ne pouvez pas l'expliquer à un enfant de six ans, vous ne le comprenez pas vous-même. Albert Einstein

Posséder certaines compétences en écriture

Je crois que les écrivains se font, ils ne naissent pas. Et vous ne pouvez apprendre à écrire qu'en écrivant réellement.

Vous ne saurez peut-être jamais que vous avez en vous la capacité d'écrire jusqu'à ce que vous mettiez la plume sur le papier. Et il n'y a qu'une seule façon de savoir si vous avez certaines compétences en écriture, et c'est en écrivant.

Je vous encourage donc à commencer à écrire dès aujourd'hui. Vous pouvez choisir de commencer avec l'une des plateformes que j'ai listées dans cette section pour étirer vos muscles d'écriture.

Et bien sûr, il est également très avantageux d'avoir une certaine expérience dans un domaine technique.

Le processus de rédaction technique

Analyser et comprendre qui sont vos lecteurs

Le plus grand facteur à considérer lorsque vous écrivez un article technique est votre public visé/attendu. Il doit toujours être au premier plan de votre esprit.

Un bon rédacteur technique écrit en fonction du contexte du lecteur. Par exemple, disons que vous écrivez un article destiné aux débutants. Il est important de ne pas supposer qu'ils connaissent déjà certains concepts.

Vous pouvez commencer votre article en décrivant les prérequis nécessaires. Cela garantira que vos lecteurs ont (ou peuvent acquérir) les connaissances dont ils ont besoin avant de plonger directement dans votre article.

Vous pouvez également inclure des liens vers des ressources utiles afin que vos lecteurs puissent obtenir les informations dont ils ont besoin en un seul clic.

Pour savoir pour qui vous écrivez, vous devez recueillir autant d'informations que possible sur qui utilisera le document.

Il est important de savoir si votre public a une expertise dans le domaine, si le sujet est totalement nouveau pour eux, ou s'ils se situent quelque part entre les deux.

Vos lecteurs auront également leurs propres attentes et besoins. Vous devez déterminer ce que le lecteur recherche lorsqu'il commence à lire le document et ce qu'il en retirera.

Pour comprendre votre lecteur, posez-vous les questions suivantes avant de commencer à écrire :

  • Qui sont mes lecteurs ?
  • De quoi ont-ils besoin ?
  • Où liront-ils ?
  • Quand liront-ils ?
  • Pourquoi liront-ils ?
  • Comment liront-ils ?

Ces questions vous aident également à réfléchir à l'expérience de votre lecteur lors de la lecture de votre écriture, dont nous parlerons plus maintenant.

Pensez à l'expérience utilisateur

L'expérience utilisateur est tout aussi importante dans un document technique que partout ailleurs sur le web.

Maintenant que vous connaissez votre public et ses besoins, gardez à l'esprit comment le document lui-même répond à ses besoins. Il est si facile d'ignorer comment le lecteur utilisera réellement le document.

Lors de l'écriture, reculez continuellement et voyez le document comme si vous étiez le lecteur. Demandez-vous : Est-il accessible ? Comment vos lecteurs l'utiliseront-ils ? Quand l'utiliseront-ils ? Est-il facile à naviguer ?

Le but est d'écrire un document qui soit à la fois utile et utilisable par vos lecteurs.

Planifiez votre document

En gardant à l'esprit qui sont vos utilisateurs, vous pouvez ensuite conceptualiser et planifier votre document.

Ce processus comprend un certain nombre d'étapes, que nous allons passer en revue maintenant.

Effectuez des recherches approfondies sur le sujet

Lors de la planification de votre document, vous devez rechercher le sujet sur lequel vous écrivez. Il existe des tonnes de ressources à seulement une recherche Google pour que vous puissiez les consulter et obtenir des informations plus approfondies.

Ne soyez pas tenté de copier les travaux ou articles d'autres personnes et de les faire passer pour les vôtres, car cela constitue du plagiat. Utilisez plutôt ces ressources comme références et idées pour votre travail.

Recherchez autant que possible sur Google, obtenez des faits et des chiffres à partir de revues de recherche, de livres ou de nouvelles, et recueillez autant d'informations que possible sur votre sujet. Ensuite, vous pouvez commencer à faire un plan.

Faites un plan

Définir le contenu de votre document avant de le développer vous aide à écrire de manière plus ciblée. Cela vous permet également d'organiser vos pensées et d'atteindre vos objectifs pour votre écriture.

Un plan peut également vous aider à identifier ce que vous voulez que vos lecteurs retirent du document. Et enfin, il établit un calendrier pour terminer votre écriture.

Obtenez des graphiques/images pertinents

Avoir un plan est très utile pour identifier les différentes aides virtuelles (infographies, gifs, vidéos, tweets) dont vous aurez besoin pour les intégrer dans différentes sections de votre document.

Et cela rendra votre processus d'écriture beaucoup plus facile si vous gardez ces graphiques pertinents à portée de main.

Écrivez dans le bon style

Enfin, vous pouvez commencer à écrire ! Si vous avez terminé toutes ces étapes, l'écriture devrait devenir beaucoup plus facile. Mais vous devez toujours vous assurer que votre style d'écriture est adapté à un document technique.

L'écriture doit être accessible, directe et professionnelle. Un texte fleuri ou émotionnel n'est pas le bienvenu dans un document technique. Pour vous aider à maintenir ce style, voici quelques caractéristiques clés que vous devriez cultiver.

Utilisez la voix active

Il est bon d'utiliser la voix active dans vos articles, car elle est plus facile à lire et à comprendre que la voix passive.

La voix active signifie que le sujet de la phrase est celui qui effectue activement l'action du verbe. La voix passive signifie qu'un sujet est le destinataire de l'action d'un verbe.

Voici un exemple de voix passive : La documentation devrait être lue six fois par an par chaque développeur web.

Et voici un exemple de voix active : Chaque développeur web devrait lire cette documentation 6 fois par an.

Choisissez vos mots avec soin

Le choix des mots est important. Assurez-vous d'utiliser le meilleur mot pour le contexte. Évitez de trop utiliser des pronoms comme « il » et « ceci » car le lecteur pourrait avoir des difficultés à identifier les noms auxquels ils se réfèrent.

Évitez également l'argot et le langage vulgaire – rappelez-vous que vous écrivez pour un public plus large dont les dispositions et inclinations culturelles peuvent différer des vôtres.

Évitez le jargon excessif

Si vous êtes un expert dans votre domaine, il peut être facile d'utiliser du jargon avec lequel vous êtes familier sans réaliser qu'il peut être déroutant pour d'autres lecteurs.

Vous devriez également éviter d'utiliser des acronymes que vous n'avez pas expliqués précédemment.

Voici un exemple :

Moins clair : Les PWAs sont vraiment considérées comme l'avenir du développement multiplateforme. Leur disponibilité sur Android et iOS en fait l'application de l'avenir.

Amélioré : Les Progressive Web Applications (PWAs) sont vraiment l'avenir du développement multiplateforme. Leur disponibilité sur Android et iOS fait des PWAs l'application de l'avenir.

Utilisez un langage simple

Utilisez moins de mots et écrivez de manière à ce que tout lecteur puisse comprendre le texte. Évitez les mots longs et compliqués. Essayez toujours d'expliquer les concepts et les termes de la manière la plus claire possible.

Formatage visuel

Un mur de texte est difficile à lire. Même les instructions les plus claires peuvent se perdre dans un document qui a une mauvaise représentation visuelle.

On dit qu'une image vaut mille mots. Cela est vrai même en rédaction technique.

Mais pas n'importe quelle image ne mérite d'être dans un document technique. Les informations techniques peuvent être difficiles à transmettre en texte seul. Une image ou un diagramme bien placé peut clarifier votre explication.

Les gens aiment aussi les visuels, donc il est utile de les insérer aux bons endroits. Considérez les images ci-dessous :

D'abord, voici un extrait de blog sans visuels :

Image

Voici un extrait du même blog, mais avec des visuels :

Image

Ajouter des images à vos articles rend le contenu plus accessible et plus facile à comprendre. En plus des images, vous pouvez également utiliser des gifs, des emojis, des intégrations (réseaux sociaux, code) et des extraits de code lorsque cela est nécessaire.

Un formatage réfléchis, des modèles, et des images ou diagrammes rendront également votre texte plus utile pour vos lecteurs. Vous pouvez consulter les références ci-dessous pour un modèle de rédaction technique de @Bolajiayodeji.

Faites une révision minutieuse

Une bonne écriture de tout type doit être exemptée d'erreurs d'orthographe et de grammaire. Ces erreurs peuvent sembler évidentes, mais il n'est pas toujours facile de les repérer (surtout dans les documents longs).

Vérifiez toujours votre orthographe (vous savez, mettez les points sur les i et les barres sur les t) avant d'appuyer sur 'publier'.

Il existe un certain nombre d'outils gratuits comme Grammarly et l'application Hemingway que vous pouvez utiliser pour vérifier les erreurs de grammaire et d'orthographe. Vous pouvez également partager un brouillon de votre article avec quelqu'un pour une relecture avant la publication.

Où publier vos articles

Maintenant que vous avez décidé de vous lancer dans la rédaction technique, voici quelques bonnes plateformes où vous pouvez commencer à publier du contenu technique gratuitement. Elles peuvent également vous aider à construire un portfolio attrayant pour que les futurs employeurs puissent le consulter.

Dev.to est une communauté de milliers de passionnés de technologie où les écrivains et les lecteurs peuvent s'engager de manière significative et partager des idées et des ressources.

Image

Hashnode est ma plateforme de blogging préférée avec des avantages incroyables tels que la cartographie de domaine personnalisée et une communauté interactive. La création d'un blog sur cette plateforme est également facile et rapide.

Image

freeCodeCamp a une très grande communauté et une portée d'audience et est un excellent endroit pour publier vos articles. Cependant, vous devrez postuler pour écrire pour leur publication avec quelques échantillons d'écriture précédents.

Votre candidature peut être acceptée ou rejetée, mais ne vous découragez pas. Vous pouvez toujours postuler à nouveau plus tard, au fur et à mesure que vous vous améliorez, et qui sait ? Vous pourriez être accepté.

Si vous écrivez pour eux, ils examineront et éditeront vos articles avant de les publier, pour vous assurer de publier l'article le plus poli possible. Ils partageront également vos articles sur leurs plateformes de réseaux sociaux pour aider plus de personnes à les lire.

Image

Hackernoon compte plus de 7 000 écrivains et pourrait être une excellente plateforme pour vous pour commencer à publier vos articles auprès des plus de 200 000 lecteurs quotidiens de la communauté.

Hacker Noon soutient les écrivains en relisant leurs articles avant de les publier sur la plateforme, les aidant à éviter les erreurs courantes.

Image

Cours de rédaction technique

Tout comme dans tout autre domaine, il existe divers processus, règles, meilleures pratiques, etc., en rédaction technique.

Suivre un cours sur la rédaction technique vous aidera à vous guider à travers tout ce que vous devez apprendre et peut également vous donner un grand coup de confiance pour démarrer votre parcours d'écriture.

Voici quelques cours de rédaction technique que vous pouvez consulter :

Forums et communautés de rédaction technique

Seuls, nous pouvons faire si peu, ensemble, nous pouvons faire tellement ~ Helen Keller

Faire partie d'une communauté ou d'un forum avec des personnes qui partagent la même passion que vous est bénéfique. Vous pouvez obtenir des retours, des corrections, des conseils et même apprendre quelques astuces de style d'autres écrivains de la communauté.

Voici quelques communautés et forums auxquels vous pouvez vous joindre :

Quelques rédacteurs techniques incroyables à suivre

Dans mon parcours de rédaction technique, j'ai rencontré et suivi quelques excellents rédacteurs techniques dont le parcours d'écriture, la constance et le style m'inspirent.

Ce sont les écrivains que je considère comme des mentors virtuels en rédaction technique. Parfois, ils donnent des conseils de rédaction technique que je trouve utiles et dont j'ai beaucoup appris.

Voici quelques-uns de ces écrivains (avec leurs identifiants Twitter) :

Mots finaux

Vous n'avez pas besoin d'un diplôme en rédaction technique pour commencer à publier du contenu technique. Vous pouvez commencer à écrire sur votre blog personnel et sur des dépôts GitHub publics tout en construisant votre portfolio et en acquérant une expérience pratique.

Vraiment – Commencez simplement à écrire.

Pratiquez en créant de nouveaux documents pour des programmes ou projets existants. Il existe un certain nombre de projets open source sur GitHub que vous pouvez consulter et auxquels vous pouvez ajouter de la documentation.

Y a-t-il une application que vous aimez utiliser, mais dont la documentation est mal écrite ? Écrivez la vôtre et partagez-la en ligne pour obtenir des retours. Vous pouvez également configurer rapidement votre blog sur hashnode et commencer à écrire.

On apprend à écrire en écrivant, et en lisant et en réfléchissant à la manière dont les écrivains ont créé leurs personnages et inventé leurs histoires. Si vous n'êtes pas un lecteur, ne pensez même pas à être un écrivain. - Jean M. Auel

Les rédacteurs techniques apprennent toujours. En plongeant dans de nouveaux domaines et en recevant des retours externes, un bon écrivain ne cesse jamais de perfectionner son art.

Bien sûr, les bons écrivains sont également des lecteurs voraces. En examinant des documents très lus ou très utilisés, votre propre écriture s'améliorera définitivement.

J'ai hâte de voir vos articles techniques !

Références

Introduction à la rédaction technique

Comment structurer un article technique

Comprendre votre public, le pourquoi et le comment

Modèle de rédaction technique

J'espère que cela a été utile. Si c'est le cas, suivez-moi sur Twitter et faites-le moi savoir !