À l'automne 2016, mon collègue et moi avons été chargés d'améliorer la documentation et le contenu de mon ancienne entreprise. Nous avons passé un an sur toutes sortes de documentation: référence API, guides, tutoriels, articles de blog. Avant cela, j'ai écrit des quais pendant 5 ans, mais je n'ai pas officiellement appris cela. Mais je ne peux pas être appelé inexpérimenté: en plus de documenter l'API pour les projets et les startups, j'ai également enseigné Python Flask lors de séminaires tout en étudiant les derniers cours à l'université. Mais maintenant, c'est l'occasion de me concentrer uniquement sur mon entreprise préférée: aider les spécialistes à tous les niveaux grâce à la documentation technique.

Cette année, j'ai beaucoup appris de la communauté Write The Docs, d'autres fournisseurs d'API et de la méthode d'essai et d'erreur. L'année dernière, j'ai partagé mon expérience dans le rapport «Ce que j'aimerais savoir sur l'écriture de documentation» à la Portland API Strategy and Practice Conference. Cet article est un aperçu des connaissances acquises.

Comment les gens lisent-ils réellement la documentation?

«Une nation frissonne devant un grand fragment d'un seul texte», photo de The Onion

Connaissez-vous ce sentiment comme sur la photo? Ça arrive. Peut-être pas physiquement, mais très probablement, les gens tremblent mentalement. J'étais constamment tourmenté par l'idée que les gens ne liraient pas mes textes à moins que je ne les rédige d'une manière facilement digestible. Mon Dieu, cela peut arriver même avec cet article.

Dans une étude de recherche réalisée en 2006 par Neilson Norman Group, 232 utilisateurs ont consulté des milliers de pages Web. Il s'est avéré que les utilisateurs regardent généralement les pages en utilisant le modèle F:

1. «D'abord, ils lisent dans le sens horizontal , généralement dans la partie supérieure de la zone de contenu. Ceci est l'élément supérieur de la figure F. "
2. «Ensuite, ils se déplacent un peu vers le bas de la page - et effectuent un deuxième mouvement horizontal , qui couvre généralement une zone plus courte que la précédente. Cet élément supplémentaire constitue l'élément central de la figure F ".
3. «Enfin, les utilisateurs scannent le côté gauche du contenu verticalement . Parfois, il s'agit d'un balayage lent et systématique, qui s'affiche sous la forme d'une bande solide sur une carte thermique. Parfois, le mouvement est plus rapide, formant des taches sur la carte thermique. Il s'agit du dernier élément vertical de la figure F. "

Cartes thermiques Nielsen Norman Group

L'étude a trouvé des modèles de balayage alternatifs, tels qu'un motif de gâteau feuilleté, une carte repérée, un modèle de disposition, un motif de dérivation et un motif utile. Je vous recommande fortement de lire le rapport .

Il est important de noter que le modèle F gêne les utilisateurs , mais un bon positionnement du contenu permet d'éviter les scans F.

Quelles sont les implications spécifiques pour la documentation?

• Les deux premiers paragraphes doivent indiquer les informations les plus importantes.
• Les 3-5 premiers mots sont critiques
• En-têtes, paragraphes et listes à puces avec des mots informatifs
• Des changements de police (taille, liens, gras, etc.) peuvent être nécessaires pour garder l'attention du lecteur

Alors, comment structurer le contenu de la page?

• Empêcher la numérisation: assurez-vous que les informations dont le lecteur a besoin sont mises en évidence
• Une réflexion sur un paragraphe. S'il y en a plusieurs, brisez le paragraphe
• Les utilisateurs ignorent tout ce qui ressemble à des bannières, alors soyez prudent avec les illustrations.
• Ne développez pas trop la colonne de texte: de manière optimale entre 65 et 90 caractères

J’ai appris certains de ces conseils lors de la conférence de Kevin Burke , «Comment écrire de la documentation pour les utilisateurs qui ne la lisent pas». Kevin a pris en charge la documentation Twilio de 2011 à 2014.

De plus, les paragraphes ont leurs propres spécificités. Comme le texte de The Onion , lorsque vous lisez beaucoup de paragraphes, vous pouvez sauter l'essentiel. Alors pourquoi les utiliser si souvent? Faisons une expérience à partir de la documentation Keen IO:

Lisez rapidement ceci:

Les ensembles d'événements peuvent avoir presque n'importe quel nom, mais il existe plusieurs règles: le nom ne doit pas comporter plus de 64 caractères. Il ne doit contenir que des caractères ASCII. Il ne peut pas être nul.

Maintenant, lisez rapidement ceci:

Les ensembles d'événements peuvent avoir presque n'importe quel nom, mais il existe quelques règles:

• Le titre ne doit pas dépasser 64 caractères
• Il ne doit contenir que des caractères ASCII
• Il ne peut pas être nul

Dans les deux exemples, exactement le même texte. Ce n’est pas le binôme de Newton: le second permet d’absorber mieux et plus rapidement les informations. Si le paragraphe contient une liste de n'importe quel type, transformez-le en liste à puces.

Plus tard, nous discuterons plus en détail de la mise en page de la documentation et de sa navigation.

Exemples de code

Qu'est-ce que la documentation de l'API sans code, non? La plupart de nos documents contiennent des exemples de code et les utilisateurs les lisent. Mais le problème est qu'ils ne prêtent pas toujours attention au texte environnant.

Le contexte dans l'exemple de code est essentiel au succès du développeur. Les développeurs adorent copier et coller rapidement. Voici un exemple avec l'API Keen IO:

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase); 

Le développeur copie et colle rapidement ce code. Et ...



Tout d'abord, comment exécutent-ils le fichier? Probablement comme node file_name.js , mais ce n'est pas dans le code. On pourrait l'indiquer dans les commentaires en haut.

Eh bien, ils l'ont commencé et ... ReferenceError: Keen is not defined . :-( Le client Keen n'a pas été lancé, en haut il n'y a aucune instruction import ou require, et cela ne fonctionne qu'après l'installation de la bibliothèque npm.

L'utilisateur l'a corrigé et relancé ... Devinez?! Encore une erreur! your_project_id et your_write_key manquants.

Tout cela pourrait être rendu plus évident.

Voici un exemple tiré de la documentation Twilio qui fournit un bon contexte pour l'utilisateur final:


Capture d'écran de la documentation de la bibliothèque Twilio Node Helper

Cela clarifie immédiatement comment installer la bibliothèque, l'intégrer dans votre code et ce qui doit être remplacé dans l'exemple de code avant de l'exécuter.

Bugs de copier-coller

Comme nous avons beaucoup d'exemples de code dans la documentation, un copier-coller réussi est une propriété assez importante. Voici deux exemples de cas où cela n'est pas respecté:

 #      $ gem install rails 

Semble assez inoffensif, non? Détrompez-vous, que se passe-t-il lorsque vous copiez et collez cela dans la ligne de commande? Vous recevrez très probablement:

 bash: command not found: $ 

Une erreur courante. Soit vous voulez que la commande ressemble à la ligne de commande, soit vous la copiez accidentellement. Je recommanderais d'abandonner $ . Vous pouvez également trouver un moyen d'interdire le copier-coller de ce symbole afin que l'erreur ne dérange pas les utilisateurs.

Un exemple plus récent: avez-vous vérifié à quel point il est facile de mettre en évidence le code que l'utilisateur veut copier?

Kelsey Hightower a eu du mal à copier l'exemple de code de StackOverflow lors de la présentation de Google Cloud Next.


"Les bons programmeurs copient, les grands programmeurs collent"

L'a-t-il fait exprès? Nous ne le saurons jamais. Cependant, ceci est une illustration de la façon dont les programmeurs tentent de mettre en évidence de gros blocs de texte sur certains sites de documentation. Assurez-vous que l'interface utilisateur du site facilite la copie de gros blocs. Vous pouvez même décomposer ces blocs pour expliquer les fragments individuellement. Ils deviendront donc plus accessibles pour la copie et la compréhension.

"C'est tout!"

"C'est tout!" La phrase semble assez inoffensive hors contexte, mais imaginez comment certains mots comme «facile», «simple», «trivial» et «simple» sont perçus lorsque vous avez des problèmes - pas génial! Lorsqu'une personne est coincée à essayer de faire fonctionner l'API, une telle phrase jette un doute sur son intelligence et lui fait poser la question: "Alors je suis stupide?" Cela démoralise.

Sur-simplification

La simplification est courante. Il est plus courant chez les débutants dans la rédaction de documentation. Souvent, les auteurs de la documentation sont en même temps les développeurs du système, donc certaines choses leur paraissent «faciles». Mais ils ont développé cette fonction, ont écrit du code pour elle, l'ont vérifiée plusieurs fois, puis ont écrit la documentation. Lorsque vous faites quelque chose des dizaines de fois, il est clair que ce sera «facile» pour vous. Mais qu'en est-il de quelqu'un qui n'a jamais vu d'interface utilisateur ou de fonction auparavant?

Empathie

Le choix des mots compte vraiment . L'empathie est la capacité de comprendre et de partager les sentiments des autres. Lorsque nous montrons de l'empathie, nous aidons non seulement les nouveaux arrivants, mais aussi les utilisateurs plus avancés. Cela permet d'augmenter le nombre potentiel d'utilisateurs, de cas d'utilisation, de clients et même les revenus de l'entreprise.

Mais lorsque la documentation est rédigée par un développeur de projet expert, l'empathie est plus difficile. Voici quelques conseils utiles qui m'ont aidé dans le passé:

• Demandez aux participants au projet moins expérimentés de commenter honnêtement la documentation.
• Encouragez les participants au projet moins expérimentés à contribuer ou à signaler des points de documentation qu'ils ne comprennent pas.
• Créez un environnement où les questions sont encouragées, y compris celles qui peuvent sembler «évidentes» aux participants expérimentés au projet - cela vous aidera à remarquer les «angles morts»
• Utilisez des processeurs de code dans les processus de révision de code et de CI pour garantir l'empathie et la convivialité linguistique pour tous les utilisateurs.
• Enfin, demandez des commentaires sur la documentation des vrais utilisateurs, montrez-leur le texte et demandez si tout est clair

Messages d'erreur comme une sorte de documentation

En règle générale, les utilisateurs sont plus susceptibles de voir des messages d'erreur que la documentation. Selon Kate Voss, "les messages d'erreur sont en fait une opportunité." Je pense que de nombreux développeurs de documentation manquent cette opportunité. Il y a une place pour la formation, l'établissement de relations de confiance et les attentes des utilisateurs. Tout d'abord, vous aiderez les gens à s'aider eux-mêmes.

Kate à Write The Docs fournit de nombreuses informations utiles sur la rédaction de messages d'erreur. J'ai beaucoup appris lors de mes précédents travaux sur les messages d'erreur des API, tout en étant de l'autre côté des barricades, recevant des messages d'erreur d'autres API en tant que développeur.

Kate dit que les bons messages d'erreur reposent sur trois principes:

• Modestie
• Humanité
• Utilité

Modestie

Vous devez vous excuser immédiatement, même si ce n'est pas de votre faute. Je pratique également cela dans le service d'assistance.

Un exemple:

Désolé, impossible de se connecter à ___. Veuillez vérifier vos paramètres réseau, vous connecter à un réseau disponible et réessayer.

Humanité

Utilisez des termes lisibles par l'homme, évitez les expressions telles que «exception levée par la cible de l'appel». Lors de l'écriture de code pour lequel de nombreux messages d'erreur sont déclenchés, il est facile de s'en tirer avec un vocabulaire clair.

Exemple (erreur de code d'état Twilio 401):

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 } 

Utilité

Si vous vous souvenez d'un de ces conseils, souvenez-vous de son utilité. Partagez des informations avec l'utilisateur sur la façon de résoudre le problème.

Un exemple:

Désolé, l'image que vous avez essayé de télécharger est trop grande. Réessayez avec des images inférieures à 4000 px de hauteur et 4000 px de largeur.

Comment écrire des messages d'erreur

Comme pour toute autre documentation, fournissez d'abord des informations importantes. Cela peut être fait en spécifiant d'abord l'objet, puis l'action. L'utilisateur recherche un résultat, pas comment y arriver. Ceci est utile lorsque les utilisateurs recherchent rapidement des messages d'erreur.

Mauvais exemple:

Appuyez sur le bouton Retour pour revenir à la page précédente.

Bon exemple:

Pour revenir à la page précédente, utilisez le bouton de retour.

Messages d'erreur de documentation

Je trouve cela très utile lorsque des messages d'erreur généraux sur l'API sont mentionnés dans la documentation. De cette façon, l'auteur de la documentation peut clarifier le message d'erreur sans agrandir la documentation, tout en aidant l'utilisateur à comprendre pourquoi l'erreur se produit.

Twilio publie un catalogue complet d'erreurs et d'avertissements avec causes et solutions possibles. En utilisant cette méthode, vous pouvez raccourcir les messages d'erreur réels, mais toujours utiles.

En cas d'erreur 20003 (erreur de code d'état 401, mentionnée précédemment), il existe de nombreuses raisons possibles qui sont clairement indiquées dans le catalogue.


Source: https://www.twilio.com/docs/api/errors

Stripe fait quelque chose de similaire avec une description détaillée des différents codes d'erreur.




Source: https://www.twilio.com/docs/api/errors

Vous pouvez même trouver vos messages d'erreur dans les questions StackOverflow. Répondez-leur modestement, humainement et avec avantage. En raison du référencement, les utilisateurs se retrouvent souvent avec vos messages d'erreur sur StackOverflow plutôt que la documentation réelle.

Astuce: si quelqu'un n'a pas répondu modestement, humainement et avec avantage, alors avec suffisamment de «réputation», vous pouvez modifier les réponses StackOverflow.

Sélection de mots

Beaucoup de mots ont des schémas mentaux bien établis. Par exemple, des mots tels que «bibliothèques», SDK, «wrappers» et «clients» sont déjà surchargés et passent à l'attention du lecteur.

Dans sa conférence, "Même pour cette conférence, il est difficile de trouver un nom" sur Write The Docs, Ruthie Bendor explique pourquoi choisir les bons mots peut être si difficile.

Nous choisissons souvent mal les mots, bien que lorsque nous écrivons du texte, nous le faisons tout le temps. Comme de nombreux titres SDK, chaque mot évoque un large éventail de sentiments, d'idées et de définitions dans le lecteur. Vous ne comprenez peut-être pas cela - et souvent, nous faisons de fausses hypothèses.

Dans une telle situation, le célèbre proverbe est plus vrai que jamais: "Il n'y a que deux tâches difficiles dans le domaine de l'informatique: l'invalidation du cache et l'invention de noms." La citation est souvent attribuée à Phil Carleton, mais aujourd'hui, il existe de nombreuses variantes de ce dicton. Parfois, à la fin, ils ajoutent "... et une erreur par unité". Ruti considère cela comme une démonstration que les logiciels d'aujourd'hui sont largement basés sur le code ou le travail de quelqu'un d'autre.

Pourquoi les mauvais noms d'objet (ou la documentation) sont-ils conservés?

Comme pour la simplification excessive, nous ne comprenons souvent pas que le nom est mauvais. C'est ce que Ruthie appelle l' échec de l'empathie . Voilà comment dire que le problème des mots infructueux ne me concerne pas, donc il n'existe pas.

Astuce pour les États-Unis: pour éviter le racisme accidentel, utilisez les mots «liste interdite» et «liste autorisée» au lieu de «noir» et «blanc».
(Sources: Andre Staltz et rails / rails / issues / 33677 )

Cela me rappelle encore ce que Ruthie appelle une erreur de pensée novice . C’est comme dire «C’est tout à fait clair pour moi. Je ne comprends pas comment quelqu'un ne peut pas comprendre cela. "

Enfin, Ruthie mentionne une erreur de localisation . Par exemple, le mot Bing en chinois signifie «malade».

Selon une étude GitHub Open Source Survey 2017 :

Près de 25% des développeurs lisent et écrivent l'anglais n'est pas «très bien». Lorsque vous communiquez dans un projet, utilisez une langue compréhensible et accessible pour les personnes des pays non anglophones.

Tenez-vous compte de cela lorsque vous utilisez des américanismes et des idiomes dans la documentation? Beaucoup d'entre eux peuvent être incompréhensibles pour les utilisateurs.

Astuce: je crois fermement que l'un des plus grands «trucs» pour résoudre ces problèmes est la diversité de l'équipe de documentation.

Il y a encore des cas où nous reconnaissons une erreur, mais nous ne pouvons pas ou ne voulons pas la corriger, parce que nous ...

• Liée à elle
• On ne trouve pas le temps
• Nous ne voyons pas l'importance
• Nous n'avons pas d'agence pour le réparer.

Vous pouvez dire ou entendre: "Mais c'est mon idée originale!", "Qui a enlevé mon chéri?" "Si nous renommons, tout se brisera", "Je ne pense pas que changer ce nom affectera quelque chose d'important."

Vous ne pouvez pas avoir peur de refactoriser et de réécrire en matière de documentation. Comment l'améliorer, si vous n'êtes pas d'accord avec le fait qu'au départ, le meilleur choix n'a pas été fait?

Comment choisir les bons mots?

Pour commencer, je recommande de poser une question: quels mots vos utilisateurs utilisent-ils? Différents cercles de programmeurs utilisent des termes différents, n'essayez pas d'en utiliser d'autres. Ceci est utile non seulement pour les lecteurs, mais aussi pour la recherche et le référencement.

En fin de compte, tout se résume inévitablement à une évaluation subjective. Cependant, il y a quelques principes à considérer. Ruthie dit que les mauvais noms sont ceux qui peuvent:

• embarrasser
• bouleverser
• induire en erreur
• confondre
• offenser

De bons noms, en revanche:

• contribuer à une clarification soudaine ("c'est tout!")
• injecté dans le contexte
• expliquer
• illuminer
• fournir un soutien

Je recommande de prendre en compte ces qualités lors de la déduction de la documentation afin de faire des critiques utiles et honnêtes à ce sujet.

Choisir les bons mots est difficile. Il n'y a pas de formule magique. Tous les utilisateurs sont différents, tout comme les cas d'utilisation des produits; ce qui fonctionne pour certains peut ne pas fonctionner pour d'autres. Si c'était facile, tout le monde aurait une bien meilleure documentation. Comme Ruthie le dit aux développeurs: «L'écriture de programmes est un exercice pour inventer des noms. Traitez-le. " Et si vous écrivez de la documentation pour le programme de quelqu'un d'autre, "dites au développeur si ses noms n'atteignent pas la cible".