Une introduction à la rédaction d'une bonne documentation

Cet article a été rédigé par l'auteur invité Jeff Matson. Jeff est le responsable de la documentation de GravityForms. Il est le créateur du plugin WordPress Heartbeat Control et est un fan des années 90.

Souvent, la documentation est la partie la plus sous-estimée du processus de développement. Lorsque nous examinons les rockstars de la communauté WordPress, nous examinons généralement les développeurs, les concepteurs et les spécialistes du marketing. On sait peu de choses sur les rédacteurs de documentation qui ont versé leur sang, leur sueur et leurs larmes pour s'assurer que tout se passe bien.

Cet article concerne ceux qui, jour après jour, regardent des lignes de code sans fin pour déchiffrer ce que pensait le développeur et la véritable signification du code existant.

Une bonne documentation est plus que des mots

Les bons rédacteurs de documentation fournissent plus qu'un manuel d'instructions, ils fournissent une expérience. J'ai connu d'excellents documenteurs, coaché ​​des débutants, et la plus grande différence entre eux est de comprendre le cerveau de ceux qui le lisent. Tout comme un roman, la documentation a un flux qui maintient le lecteur intéressé et ingère plus d'informations qu'il ne le pense.

Une documentation de qualité cible les utilisateurs les plus susceptibles de la lire. Il fournit également un point de référence pour ceux qui sont moins susceptibles de le lire. Par exemple, si vous documentez un crochet particulier, on suppose généralement qu'un développeur le lira, mais qu'en est-il de ceux qui ont peu d'expérience en développement ?

Un bon rédacteur de documentation fournira un point de référence à ceux qui ont besoin d'un coup de pouce dans la bonne direction, sans avoir besoin de contacter le support pour le leur expliquer.

La documentation a un impact plus important que vous ne le pensez

La plupart ignorent simplement la documentation, la poussant dans l'abîme sans fin jusqu'à ce qu'ils n'en puissent plus. Je suis coupable de la même chose dans certains cas. Ce que ces personnes ne réalisent pas, c'est qu'à chaque instant leur plugin ou thème n'est pas documenté, l'expérience utilisateur en souffre.

Examinons votre ticket d'assistance le plus courant. Si vous documentiez mieux ce problème, ces tickets disparaîtraient-ils complètement ? Probablement pas. Recevriez-vous moins de tickets concernant le problème et augmenteriez-vous votre productivité ou celle de votre agent de support ? Je le garantis. Je pense que nous pourrions tous utiliser moins de tickets d'assistance.

Comme je l'ai mentionné précédemment, la documentation a un impact considérable sur l'expérience utilisateur. Si l'utilisateur est capable de localiser les informations facilement et efficacement, il a économisé son temps ainsi que le vôtre. L'espérance de vie moyenne dans le monde est de 66,57 ans et vos utilisateurs préféreraient faire autre chose de leur vie plutôt que de jouer avec une documentation mal écrite.

Si un client voit que vous avez consacré pas mal de temps et d'efforts à votre documentation, il vous appréciera, consciemment ou non. Une bonne documentation montre que vous vous souciez d'eux après la vente initiale.

Avez-vous déjà été laissé au sec après avoir dépensé de l'argent durement gagné et avez-vous rapidement regretté l'achat ? Je pense que nous avons tous. Avec une documentation appropriée, vous pouvez éviter de transmettre ce sentiment à vos clients.

Comment rédiger une meilleure documentation ?

La première étape est d'arrêter de l'éviter. Une fois que vous y êtes bon, écrire de la documentation est une expérience plus agréable que vous ne le pensez. En fait, cela deviendra une seconde nature. Comme tout le reste dans le monde, la pratique rend parfait.

L'une des premières étapes à suivre lorsque vous décidez de faire passer votre documentation au niveau supérieur consiste à déterminer vos points faibles. A propos de quoi êtes-vous contacté ? Si vous commencez à écrire aveuglément sur des choses, vous constaterez peut-être que ce que vous écrivez n'a pas autant d'impact que vous le souhaiteriez.

L'une des meilleures techniques que j'ai découvertes consiste à suivre le nombre de tickets documentés par rapport à ceux qui ne le sont pas, et à répartir ceux qui ne le sont pas en catégories. De cette façon, vous pouvez mieux cibler vos points faibles et réviser les parties qui pourraient ne pas être aussi utiles qu'elles le devraient.

Après avoir déterminé quelle documentation vous devez écrire, vous devez déterminer votre public cible et le décomposer en développeurs, utilisateurs et utilisateurs expérimentés. Cela vous aide à répondre à ce public particulier. Nous verrons comment cibler ces utilisateurs un peu plus tard.

Ensuite, vous voulez décomposer le document. Pour les développeurs, vous voudrez le décomposer en informations brutes (arguments acceptés, valeurs de retour, etc.), exemples spécifiques et cas d'utilisation. Pour les utilisateurs, le meilleur plan d'action est une procédure pas à pas. Chaque étape qu'ils devront franchir, aussi insignifiante soit-elle, est essentielle.

Expliquez-leur à chaque étape du chemin. La documentation pour les utilisateurs expérimentés est très similaire à un scénario utilisateur, mais plus structurée et analysable. Soyez clair, mais permettez-leur de sauter facilement là où ils doivent aller sans lire l'étape précédente au préalable.

L'art de rédiger une meilleure documentation

En ce qui concerne l'art de rédiger votre documentation, écrivez d'une manière qui cible au mieux votre public, mais utilisez également un langage simple que vous savez qu'il comprendra. L'une des meilleures raisons à cela est due aux traductions. Bien que Google Translate fasse un excellent travail, il est beaucoup plus facile de traduire le vocabulaire simple d'un élève de 5e que celui contenu dans une thèse de troisième cycle.

Dans votre contenu, n'ayez pas peur de créer un lien vers un contenu pertinent. Cela vous permettra d'éviter de vous répéter dans plusieurs documents, ainsi que de permettre au lecteur de revenir en arrière s'il a besoin de plus d'informations sur un sujet particulier. Après tout, vos principaux objectifs sont de rendre l'utilisateur heureux et de gagner du temps.

Le processus de documentation ne s'arrête pas après avoir appuyé sur le bouton de publication . Revenez en arrière et révisez chaque document au besoin. Presque immédiatement après la publication du document, revenez en arrière et voyez si les tickets d'assistance que vous avez suivis ont diminué et si le trafic vers cet article particulier a augmenté. Habituellement, si vous obtenez plus de trafic vers un article, cela aide. Si vous obtenez plus de trafic mais le même nombre de tickets d'assistance, vous voudrez peut-être consulter cet article pour voir pourquoi.

Ce que nous avons appris

Tout d'abord, j'espère qu'après être arrivé jusqu'ici, vous aurez une meilleure appréciation de ceux qui, dans les tranchées, écrivent la documentation que la plupart d'entre nous tenons pour acquise. C'est vraiment une forme d'art que beaucoup d'entre nous qui écrivons de la documentation pour gagner leur vie apprécient vraiment et y consacrent de très nombreuses heures.

J'espère également que vous sortirez de cet article en pensant davantage à votre documentation existante et à la manière dont elle peut être améliorée. Une bonne documentation peut être extrêmement gratifiante et une fois en pratique, peut en fait être assez amusante à écrire.

Documentez tôt, documentez souvent. Un excellent produit est plus qu'un excellent code, il est également magnifiquement documenté.