50 questions pour travailler sur la documentation

Peu importe les efforts du concepteur UX, une personne de la rue ne pourra pas comprendre l'interface de contrôle du vaisseau spatial sans un indice. Et même pas de la rue. Tout simplement parce que la fusée est grosse et qu'il y a beaucoup de réglages.

Nous rendons les produits plus simples que les logiciels pour fusées, mais toujours techniquement sophistiqués. Nous essayons très fort pour que les interfaces des nouvelles versions soient simples, mais nous nous rendons compte qu'il y aura toujours un utilisateur qui ne comprendra pas quelque chose et ira à la documentation. Par conséquent, il devrait y avoir un quai, et afin de ne pas gâcher l'impression du produit, il devrait être utile et pratique.

Nous avons six produits, dont la documentation depuis la fondation de l'entreprise a été rédigée par les développeurs. Depuis six mois, nous réécrivons d' anciens articles et écrivons de nouveaux articles . Under the cut - 50 questions qui nous aident à bien faire cela. Mais pour commencer, une petite introduction.

Pourquoi la documentation est importante et qui devrait le faire

Faire un bon quai est difficile. Quelque part, un énorme département d'analystes, d'écrivains et d'éditeurs y travaille, et quelque part les développeurs écrivent sur le dock (fait - décrit).

Nous avons deux rédacteurs techniques sur six produits avec plusieurs versions. Ce n'est pas suffisant, donc les chefs de produit, les testeurs, la première ligne de support et de marketing travaillent sur le dock. Ils n'écrivent pas d'articles, mais aident à comprendre le produit et les tâches du client, choisissent un sujet et collectent des informations, vérifient le contenu et la conception de l'article fini. Ensemble, nous améliorons le quai.

Si vous avez un petit département techwriter, recrutez du personnel dans d'autres départements. S'ils ne sont pas intéressés, donnez des arguments de la liste ci-dessous. Premier support, deuxième et troisième marketing et marketing produit. Alors pourquoi la documentation est-elle importante?

1. Facteur de soutien . La première et la plus évidente des raisons. Si la documentation est bonne, la plupart des clients résoudront le problème sans contacter le support. Le support restant jettera un lien vers les instructions ou passera rapidement par moi-même. Une documentation complète peut être utilisée pour créer des robots de discussion. Tout cela réduit le temps de réponse des clients, augmente leur satisfaction et réduit également les coûts de support.
2. Facteur de sélection . La documentation affecte le choix du client ainsi que le prix, la commodité, la fonctionnalité. Cela est confirmé par nos recherches et les commentaires des utilisateurs ISPmanager et DCImanager . Dans cette optique, le quai cesse d'être une nécessité de soutien, mais devient un avantage concurrentiel, faisant partie du marketing.
3. Facteur de fidélité . Si le client est parti sans comprendre le dock au début ou dans le processus, c'est un problème. Attirer un client coûte trop cher à perdre en raison de mauvais articles.

Comment faire une bonne documentation

Définissez un objectif . C'est le plus douloureux. Décrire une fonctionnalité juste pour la description ou commenter une interface n'est pas le but. Un objectif est toujours une action bénéfique. Qu'est-ce qu'un utilisateur, un administrateur ou un développeur doit savoir et pouvoir lire après avoir lu un article? Par exemple, créez un site et liez-y un domaine, émettez un certificat SSL, configurez des sauvegardes, etc. Autrement dit, résolvez votre problème.

Connaissez le public . Nous divisons les clients en utilisateurs, administrateurs et développeurs. Mais cela ne suffit pas pour créer des textes utiles. Pour comprendre rapidement le public, vous pouvez vous rendre sur UX et le produit, étudier les demandes d'assistance et leurs réponses sur le sujet, écouter les appels de première ligne, consulter le site et le blog (le marketing écrit également les éléments nécessaires). Et seulement après cela, commencez à écrire.

Vérifiez, modifiez et vérifiez à nouveau . Les rédacteurs techniques devraient faire une première vérification. Après elle un de plus. Ensuite, il convient de connecter l'assistance, le marketing et d'autres services à l'audit. Ensuite, vous devez vérifier avec le manuel de style et de conception - la politique éditoriale. Quelqu'un du côté ou d'un autre rédacteur technique l'a laissé faire la relecture finale. Si vous avez un éditeur, il se chargera de cette étape.

Distribuez l'article après sa publication . Si la documentation est écrite, il est probable que quelqu'un en aura besoin. Montrez-le à la lumière et utilisez-le au maximum: traduire, faire référence au produit, le donner au marketing, au support. N'écrivez pas sur la table.

50 questions à travailler sur le quai

En travaillant sur la documentation, nous avons répété les mêmes erreurs. Ils ont passé trop de temps à vérifier les articles, et le guide, qui au départ semblait être une panacée, n'a pas aidé, car le problème était dans l'approche et le contenu. Afin que les rédacteurs techniques puissent rapidement et rapidement se souvenir de l'article, nous avons regroupé dans une liste toutes les questions que nous leur posions constamment (ou oublions de poser). À utiliser également lors de l'écriture d'un dock.

Buts

1. Pour qui suis-je en train d'écrire un article? Qui est le futur lecteur: utilisateur, administrateur, développeur?
2. À quelles tâches doit-il faire face (travaux à effectuer)? Y a-t-il une description de la personne?
3. Quel est le niveau de formation de cet utilisateur? Que sait-il déjà? Qu'est-ce qui n'est pas évident pour lui?
4. Comment puis-je expliquer cela à un utilisateur novice, et en même temps ne pas irriter l'explication avancée des choses de base?
5. Que faut-il expliquer d'autre à l'utilisateur pour qu'il comprenne le contenu principal de l'article?
6. À quelle section de la documentation cet article convient-il?
7. Cet article ou une partie de celui-ci doit-il être reproduit dans d'autres sections?
8. À quels articles dois-je créer un lien?
9. Peut-être que cet article devrait être accompagné d'une instruction vidéo?

Sources d'information

10. Les utilisateurs actuels ont-ils des problèmes avec le sujet de l'article?
11. Comment le soutien explique-t-il maintenant ce qui doit être fait?
12. Le service marketing a-t-il rédigé des articles de blog et des actualités sur ce sujet? Peuvent-ils «espionner» leur formulation, leur structure, etc.?
13. Y a-t-il des sections sur ce sujet sur le site?
14. Qu'est-ce que le script comprenait l'UX et le chef de produit? Pourquoi a-t-il fait ça?
15. Comment cette question est-elle décrite par les concurrents?
16. Dans quels domaines voyez-vous encore les meilleures pratiques?

Vérification du contenu

17. Avez-vous atteint l'objectif de l'article?
18. Tout sera clair pour un utilisateur plus avancé?
19. Tout sera clair pour un utilisateur novice?
20. Tout est-il logique et cohérent? Pas de sauts et d'abîmes?
21. La séquence d'actions est-elle correcte? L'utilisateur pourra-t-il atteindre l'objectif en suivant uniquement cette instruction?
22. Avons-nous pris en compte tous les cas / chemins utilisateur?
23. L'article s'inscrit-il dans la section sélectionnée?

Vérification de la mise en page

24. Y a-t-il des feuilles de texte illisibles? Est-il possible de remplacer le circuit?
25. Y a-t-il de longs paragraphes?
26. Y a-t-il des paragraphes trop courts?
27. Y a-t-il des listes trop longues?
28. Y a-t-il des listes trop compliquées pour la perception (celles où il y a plus de deux ou trois niveaux)?
29. Y a-t-il suffisamment d'images?
30. Pas trop d'images? Illustrons-nous des étapes trop évidentes?
31. S'il existe des régimes, sont-ils compréhensibles?
32. Les tableaux ne sont pas difficiles à percevoir?
33. La page semble-t-elle globalement bonne?

Édition littéraire

34. Tout est-il conçu selon le guide?
35. Le style du reste de la documentation est-il cohérent?
36. Des suggestions qui peuvent être simplifiées?
37. Y a-t-il des termes complexes qui nécessitent une clarification?
38. Y a-t-il un cléricalisme?
39. Y a-t-il une répétition?
40. Rien ne fait mal à votre audition?

Relecture finale

41. Y a-t-il des fautes de frappe, des fautes d'orthographe ou de ponctuation?
42. Les tirets, paragraphes et sections sont-ils corrects?
43. Toutes les images sont-elles signées?
44. Les éléments d'interface sont-ils nommés correctement?
45. Y a-t-il des liens partout? Travaillent-ils et où vont-ils?

Immédiatement après la publication

46. ​​L'article comporte-t-il des sections qui sont «tirées» dans d'autres articles? Sont-ils décorés de macros pour que les modifications d'un article soient automatiquement appliquées aux autres?
47. Cet article devrait-il être référencé à partir d'autres sections? Si oui, lequel?
48. Besoin d'ajouter un lien rapide vers cet article dans le produit?
49. Dois-je envoyer le lien vers le support, le marketing ou d'autres services?
50. Dois-je soumettre un article à traduire?

Cette liste peut être imprimée et placée sur le bureau ou accrochée au mur. Ou transformez-vous en liste de contrôle. Certaines des questions peuvent être intégrées au processus opérationnel. Le nôtre, par exemple, est fixé dans le processus de développement général de YouTrack. La tâche de documentation passe par différentes étapes et départements, sans documentation écrite, vous ne pouvez pas donner une fonctionnalité à publier.