Rédaction technique pour les débutants - Un guide AZ sur les bases du blogage technique

Si vous aimez l'écriture et la technologie, la rédaction technique pourrait être une carrière qui vous convient. C'est aussi quelque chose que vous pouvez faire si vous aimez la technologie mais n'avez pas vraiment envie de coder toute la journée.

La rédaction technique peut également être pour vous si vous aimez apprendre en enseignant aux autres, en contribuant à des projets open source et en enseignant aux autres comment le faire aussi, ou si vous aimez essentiellement expliquer des concepts complexes de manière simple à travers votre écriture.

Plongeons dans les principes fondamentaux et apprenons ce que vous devez savoir et prendre en compte lorsque vous vous lancez dans la rédaction technique.

Table des matières

Dans cet article, nous examinerons:

  • Qu'est-ce que la rédaction technique
  • Avantages de la rédaction technique
  • Compétences nécessaires à avoir en tant que rédacteur technique
  • Le processus de rédaction technique
  • Plateformes de publication de vos articles
  • Cours de rédaction technique
  • Forums et communautés de rédaction technique
  • Quelques rédacteurs techniques incroyables à suivre
  • Mots finaux et références

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

La rédaction technique est l'art de fournir des instructions axées sur les détails 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, également appelées documentation technique ou tutoriels. Cela peut inclure des manuels d'utilisation, des articles d'assistance en ligne ou des documents internes pour les codeurs / développeurs d'API.

Un rédacteur technique communique d'une manière qui présente des informations techniques afin que le lecteur puisse utiliser ces informations dans un but prévu.

Avantages de la rédaction technique

Les rédacteurs techniques sont des apprenants permanents. Étant donné que le travail implique la communication de concepts complexes en termes simples et directs, vous devez bien connaître le domaine sur lequel vous écrivez. Ou soyez prêt à en savoir plus.

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

La rédaction technique vous donne également un meilleur sens de l'empathie de l'utilisateur. Cela vous aide à accorder plus d'attention à ce que ressentent les lecteurs ou utilisateurs d'un produit 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 quelques organisations qui vous paient pour écrire pour elles, comme Smashing Magazine, AuthO, Twilio et Stack Overflow.

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

Vous pouvez également vous lancer dans la rédaction technique en tant que profession à plein temps - de nombreuses entreprises ont besoin de quelqu'un possédant ces compétences.

Compétences nécessaires à avoir en tant que rédacteur technique

Comprendre l'utilisation d'un anglais correct

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

Savoir expliquer les choses clairement et simplement

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

Pour être un bon enseignant, vous devez faire preuve d'empathie et avoir la capacité d'enseigner ou de décrire des termes d'une 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 des compétences en rédaction‌‌

Je crois que les écrivains sont faits, pas nés. Et vous ne pouvez apprendre à écrire qu'en écrivant réellement.

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

Je vous encourage donc à commencer à écrire aujourd'hui. Vous pouvez choisir de commencer avec l'une des plates-formes que j'ai répertoriées dans cette section pour étirer vos muscles d'écriture.

Et bien sûr, c'est aussi un énorme avantage d'avoir une certaine expérience dans un domaine technique.

Le processus de rédaction technique

Analysez et comprenez qui sont vos lecteurs

Le principal facteur à prendre en compte lorsque vous rédigez un article technique est votre public cible / attendu. Cela devrait toujours être au premier plan de votre esprit.

Un bon rédacteur technique écrit en fonction du contexte du lecteur. À titre d'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 conditions préalables 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.

Afin de savoir pour qui vous écrivez, vous devez rassembler 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 lui ou s'il se situe 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 retire.

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 en lisant votre texte, dont nous parlerons plus en détail maintenant.

Pensez à l'expérience utilisateur

L'expérience utilisateur est tout aussi importante dans un document technique que n'importe où sur le Web.

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

Pendant que vous écrivez, reculez continuellement et visualisez le document comme si vous étiez le lecteur. Demandez-vous: est-ce accessible? Comment vos lecteurs l'utiliseront-ils? Quand l'utiliseront-ils? La navigation est-elle facile?

L'objectif est de rédiger un document à 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.

Mener des recherches approfondies sur le sujet

Lors de la planification de votre document, vous devez rechercher le sujet sur lequel vous écrivez. Il y a des tonnes de ressources que seule une recherche Google vous permet de consommer et d'obtenir des informations plus approfondies.

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

Google autant que possible, obtenez des faits et des chiffres dans des revues de recherche, des livres ou des actualités, et rassemblez autant d'informations que possible sur votre sujet. Ensuite, vous pouvez commencer à faire un contour.

Faire un contour

Décrire le contenu de votre document avant de le développer vous aide à écrire de manière plus ciblée. Il 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) que vous devrez 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 convient à 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 à conserver ce style, voici quelques caractéristiques clés que vous devriez cultiver.

Utiliser Active Voice

C'est une bonne idée d'utiliser des voix actives dans vos articles, car elles sont plus faciles à lire et à comprendre que la voix passive.

La voix active signifie que le sujet de la phrase est celui qui exécute 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 doit ê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 tels que «ça» et «ceci» car le lecteur peut 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 la disposition et les 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 le jargon que vous connaissez sans vous rendre compte qu'il peut être déroutant pour les autres lecteurs.

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

Voici un exemple :

Moins clair: les PWA sont vraiment considérés comme l'avenir du développement multiplateforme. Leur disponibilité sur Android et iOS en fait l'application du futur.

Amélioré: les applications Web progressives (PWA) représentent vraiment l'avenir du développement multiplateforme. Leur disponibilité sur Android et iOS fait des PWA l'application du futur.

Utilisez un langage simple

Utilisez moins de mots et écrivez de manière à ce que tout lecteur puisse comprendre le texte. Évitez les mots trop longs. 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 être perdues dans un document dont la représentation visuelle est médiocre.

Ils disent qu'une image vaut mille mots. Cela sonne vrai même dans la rédaction technique.

Mais pas n'importe quelle image n'est digne d'un document technique. Les informations techniques peuvent être difficiles à transmettre uniquement dans le texte. Une image ou un diagramme bien placé peut clarifier votre explication.

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

Tout d'abord, voici un extrait de blog sans visuels:

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

L'ajout d'images à vos articles rend le contenu plus compréhensible et plus facile à comprendre. En plus des images, vous pouvez également utiliser des gifs, des emoji, des intégrations (médias sociaux, code) et des extraits de code si nécessaire.

Une mise en forme, des modèles et des images ou des diagrammes bien pensés rendront également votre texte plus utile à vos lecteurs. Vous pouvez consulter les références ci-dessous pour un modèle de rédaction technique de @Bolajiayodeji.

Faites un examen attentif

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

Vérifiez toujours votre orthographe (vous savez, marquez votre Est et croisez votre Ts) avant de cliquer 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 le relire avant de le publier.

Où publier vos articles

Maintenant que vous avez décidé de vous lancer dans la rédaction technique, voici quelques bonnes plates-formes sur lesquelles vous pouvez commencer à mettre en place du contenu technique gratuitement. Ils peuvent également vous aider à créer un portefeuille attrayant pour les futurs employeurs.

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

Hashnode est ma plateforme de blogs de choix avec des avantages impressionnants tels que le mappage de domaine personnalisé et une communauté interactive. La création d'un blog sur cette plateforme est également simple et rapide.

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

Votre candidature peut être acceptée ou rejetée, mais ne vous découragez pas. Vous pouvez toujours présenter une nouvelle demande plus tard à mesure que vous vous améliorez, et qui sait? Vous pourriez être accepté.

Si vous écrivez pour eux, ils examineront et modifieront vos articles avant de les publier, afin de vous assurer de publier l'article le plus soigné possible. Ils partageront également vos articles sur leurs plateformes de médias sociaux pour aider davantage de personnes à les lire.

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

Hacker Noon soutient les rédacteurs en relisant leurs articles avant de les publier sur la plateforme, ce qui les aide à éviter les erreurs courantes.

Cours de rédaction technique

Comme dans tous les autres domaines, il existe différents processus, règles, meilleures pratiques, etc. en rédaction technique.

Suivre un cours de rédaction technique vous guidera à travers tout ce que vous devez apprendre et peut également vous donner un regain de confiance majeur pour démarrer votre parcours d'écriture.

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

  • Cours de rédaction technique Google (gratuit)
  • Cours de rédaction technique Udemy (payant)
  • Bootcamp de rédaction technique Hashnode (gratuit)

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 commentaires, des corrections, des conseils et même apprendre des conseils de style d'autres rédacteurs de la communauté.

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

  • Hashnode
  • Dev.à
  • Monde de la rédaction technique
  • Forum des rédacteurs techniques
  • Rédiger le forum Docs

Quelques rédacteurs techniques incroyables à suivre

Dans mon parcours d'écriture technique, je suis venu et j'ai suivi de grands écrivains techniques dont le parcours d'écriture, la cohérence et le style m'inspirent.

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

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

  • Quincy Larson
  • Edidiong Asikpo
  • Fosse Catalin
  • Victoria Lo
  • Bolaji Ayodeji
  • Amruta Ranade
  • Chris Bongers
  • Colby Fayock

Derniers mots

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 les référentiels publics GitHub tout en créant votre portefeuille 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 ajouter à leur documentation.

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

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

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

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

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 d'écriture technique

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