Comment créer une documentation technique efficace pour votre application Shopify

Documentation technique application

La plupart des développeurs n'aiment pas rédiger des documents techniques, ils préfèrent largement coder ! Mais la documentation est parfois nécessaire. Voici quelques conseils pour vous aider à créer du contenu efficace pour appuyer votre application Shopify destinée aux marchands.

Avant de plonger dans le vif du sujet, prenons le temps de clarifier ce que nous entendons par « documentation ». Nous allons aborder ici certains concepts généraux sur la création d'articles ou de sujets pour accompagner votre application : du contenu supplémentaire qui aide les marchands à prendre en main votre application, qui leur apprend à l'utiliser et qui leur permet de résoudre d'éventuels problèmes. C'est ce qu'on appelle souvent « aide » ou encore « guide d'utilisation ».

Bien que cette documentation soit distincte de votre application, mieux vaut la considérer comme une partie intégrante de votre offre. Apportez-y autant de soin qu'à la conception et au codage de votre application elle-même. Votre documentation technique est également un outil marketing, qui démontre votre professionnalisme. Elle doit refléter la qualité de votre application et peut même contribuer à augmenter son adoption.

1. Soignez l'expérience utilisateur pour simplifier la documentation

Une application bien conçue offrira une excellente expérience utilisateur, avec des fonctionnalités intuitives qui n'auront pas besoin d'être expliquées. C'est parfait ! Vous serez soulagé d'avoir moins de documentation à rédiger, et les marchands seront ravis d'avoir moins d'explications à lire.

Le choix des mots que vous employez dans l'application elle-même (ce que l'on appelle généralement le « texte de l'interface utilisateur ») est primordial. Ces mots sont ceux que verront vos utilisateurs, et ce sont eux qui doivent les guider pour chaque action.

Le texte de l'interface utilisateur est en lui-même un type de documentation. Une application inclut en général des champs où un marchand peut entrer des données, des boutons sur lesquels il peut cliquer, etc. Assurez-vous que les termes choisis pour chacun de ces différents éléments d'interface soient parfaitement clairs, afin que l'utilisateur comprenne immédiatement leur fonction.

Si les intitulés ne permettent pas d’être assez précis, vous pouvez ajouter quelques lignes de texte pour expliquer ce qui doit être fait sur un écran ou dans une zone spécifique.

Nous n'entrerons pas dans les détails de ce type de documentation ici, mais vous pouvez consulter les directives du système Polaris de Shopify pour découvrir comment concevoir la meilleure interface utilisateur pour votre application.

Retenez qu'en général, une application bien documentée dans l'interface utilisateur elle-même sera plus facile à utiliser pour les marchands, et nécessitera donc moins de documentation technique.

2. Gardez toujours vos utilisateurs (les marchands Shopify) à l'esprit

Vous concevez vos applications pour les marchands, vous devez rédiger votre documentation pour eux aussi.

Par exemple, quand vous concevez votre application, vous tenez certainement compte du niveau de connaissances estimé de vos utilisateurs, que ce soit en matière de stock, de marketing, d'expédition ou de tout autre aspect de la gestion d'une entreprise. De la même façon, votre documentation doit reprendre le langage que les marchands utilisent au quotidien dans leurs activités.

Prenons l'exemple du titre. Imaginons que vous ayez créé une application qui facilite un aspect précis de la gestion des retours et des échanges en ligne. Imaginons maintenant que vous proposez ce titre aux marchands dans votre documentation :

Certification des produits renvoyés au lieu de vente

Pardon ? Ce texte a-t-il été écrit par un robot ? Si vous disiez plutôt :

Autoriser les retours

C'est beaucoup plus clair ! Ce nouveau titre utilise un langage que les marchands comprennent et utilisent sûrement eux-mêmes tous les jours. Un utilisateur qui parcourt rapidement votre documentation saura exactement de quoi parle cet article.

Assurez-vous que les termes que vous utilisez dans votre documentation sont courants et bien compris par les marchands.

Cette recommandation vaut aussi pour le jargon technique. En tant que développeur, des mots comme « API », « méthode » ou « journal d'erreur » vous sont probablement familiers. Mais de nombreux marchands ne comprennent pas ces termes ou ce à quoi ils font référence dans votre application. Il vaut donc mieux les éviter.

L'article relatif à Launchpad du Centre d'aide Shopify est un parfait exemple de contenu adapté aux marchands. Ses premières lignes présentent les fonctionnalités de cette application Shopify Plus et expliquent précisément en quoi elle peut être utile aux marchands.

Ce conseil peut vous paraître simple, garder son public en tête semble être évident. Mais il est très facile de tomber dans le piège d'écrire ce que vous savez plutôt que ce que vos lecteurs ont besoin de savoir. Nous reviendrons sur ce point un peu plus tard.

3. Commencez à écrire la documentation en même temps que le code

Certaines personnes pensent qu'il faut s'attaquer à la documentation une fois le code terminé. Après tout, comment pourriez-vous expliquer l'utilisation d'une application qui n'est même pas encore créée ?

Et bien non ! En fait, il est très important de commencer à rédiger votre contenu bien plus tôt. Une documentation est plus efficace lorsqu'elle est conçue comme du code : un prototype, puis un autre et encore un autre, jusqu'à parvenir à la version finale.

Votre première version sera sûrement loin d'être parfaite, et c'est tout à fait normal. L'important est de commencer à noter vos idées pour pouvoir ensuite réécrire, modifier, et réécrire encore et encore — comme pour votre code, que vous améliorez sans cesse jusqu'à ce qu'il ne contienne plus aucune erreur et qu'il remplisse parfaitement vos objectifs.

Si vous disposez des ressources nécessaires, l'idéal est de faire appel à quelqu'un qui n'a pas participé au développement de l'application pour écrire la documentation. Un rédacteur technique ou un concepteur de contenu professionnel, par exemple, sera à même de définir et de rédiger le contenu pour vous. Même si vous faites appel à un prestataire pour rédiger votre documentation, vous devez l'impliquer dans votre projet le plus tôt possible pour qu'il ait une bonne compréhension de votre application et du contexte général. Pour approfondir ce sujet, consultez mon article en anglais sur Medium, Is your technical writer a garnish, or a main ingredient? (Votre rédacteur technique est-il un simple accompagnement ou un ingrédient essentiel ?).

4. Créez une documentation axée sur les tâches

Vous pouvez créer deux types de documentation : une documentation qui explique comment votre application fonctionne ou une documentation qui explique comment faire fonctionner votre application.

Celle qui explique comment votre application fonctionne est en général plus technique, elle sert de référence aux utilisateurs plus pointus dans le domaine. Ce contenu est parfois défini comme « axé sur les fonctionnalités ».

Au contraire, le contenu de votre application devrait expliquer comment la faire fonctionner. En d'autres termes, il devrait fournir des instructions qui expliqueront aux marchands comment utiliser votre application pour parvenir à leurs objectifs. Cette documentation est « axée sur les tâches ».

Lorsqu'un marchand ajoute votre application à sa boutique Shopify, il veut qu’elle résolve un problème spécifique. En fonction des caractéristiques de votre application, il devra peut-être d'abord la configurer d'une manière ou d'une autre, transférer des données ou régler certains paramètres avant que l'application puisse être opérationnelle.

Ces tâches de configuration d'une application pour des besoins spécifiques sont les premières pour lesquelles vous devez rédiger du contenu.

Vous pouvez ensuite passer aux autres tâches à effectuer pour utiliser l'application.

Voici un exemple pour vous permettre de mieux différencier ces deux types de documentation. Une documentation axée sur les fonctionnalités peut proposer un sujet « Structure de fichier CSV », qui décrit les différentes colonnes d'un fichier de valeurs séparées par des virgules (CSV) et les types de données pour chaque colonne, ainsi qu'un sujet « Exportation CSV » qui explique comment les données de ce fichier peuvent être utilisées par un autre système.

À l’inverse, les sujets d'une documentation axée sur les tâches peuvent être par exemple :

  • Ajouter vos produits au fichier CSV
  • Vérifier les produits dans le fichier CSV
  • Exporter votre stock vers un autre système

Remarquez ici que les titres à eux seuls suffisent à définir les tâches que le marchand est susceptible de vouloir exécuter. Ils utilisent aussi des termes clairs et concrets, que le marchand connaît certainement.

Les marchands préfèreront en général la documentation axée sur les tâches. La plupart des articles du Centre d'aide Shopify sont rédigés dans cette optique.

5. Faites relire et tester votre documentation par un œil extérieur

Votre documentation doit être relue et testée aussi soigneusement que votre application elle-même. Et il est important que ces vérifications soient en partie effectuées par des personnes qui ne connaissent pas bien votre application. Ne faites pas tout vous-même !

Faites appel à une personne extérieure, qui n'est pas un expert de votre application. Un relecteur indépendant, qui n'a pas participé au développement de l'application, ne la connaîtra forcément pas aussi bien que vous. Il pourra donc apporter un regard neuf sur la documentation, tandis que votre avis sera nécessairement faussé. Ce biais cognitif est parfois appelé la « malédiction de la connaissance ». Pour plus d’informations sur ce concept, consultez la page Wikipédia correspondante ou le livre de Steven Pinker The Sense of Style (Le sens du style).

Pour expliquer brièvement ce concept, disons que si vous effectuez la relecture vous-même, vous risquez d'être imperceptiblement influencé par votre expertise de l'application et du contenu que vous avez vous-même rédigé. Au contraire, un œil extérieur sera plus à même de remarquer que l'approche utilisée n'est pas assez orientée sur les tâches, que certains passages doivent être complétés ou que des informations ne sont plus à jour. Il pourra aussi vous aider à repérer les fautes de frappe que vous ne voyez plus.

Faites relire votre documentation par une personne autre que les développeurs, votre documentation s’en trouvera forcément améliorée.

Une documentation claire, des utilisateurs satisfaits

La rédaction de votre contenu d'aide n'est sûrement pas votre priorité ni votre tâche préférée, mais prenez le temps de créer une documentation complète, qui aidera les marchands à bien utiliser votre application. Cela en vaut la peine.

Les quelques conseils donnés dans cet article ne font qu'effleurer la surface de tout ce qu'implique la création d'une documentation technique.

Voici quelques ressources utiles (en anglais) si vous souhaitez aller plus loin :

  • Le site de l'organisation « Write the Docs » est une véritable mine d'informations, dont un Guide de documentation très complet.
  • Google propose des cours d'initiation à la rédaction technique.
  • Le livre Strategic Writing for UX (Écriture stratégique pour l’expérience utilisateur) de Torrey Podmajersky est principalement axé sur le contenu de l'interface utilisateur, mais couvre énormément de sujets dans un petit format.
  • La société Bold Commerce a créé plusieurs applications Shopify et le contenu d'aide correspondant. Inspirez-vous de leur approche de la documentation technique.

Quelle que soit la manière dont vous abordiez la documentation technique, retenez ces 3 grands conseils : concentrez-vous sur les objectifs des marchands, adoptez un langage simple et direct, et n'oubliez pas de faire relire vos documents par un tiers avant de les publier.

Rejoignez le programme des partenaires de Shopify

Inscrivez-vous gratuitement au programme partenaire de Shopify. Accédez à des outils et ressources pour aider les marchands Shopify à développer leur activité et faites partie d’un écosystème riche en opportunités.

Devenir partenaire Shopify

Which method is right for you?Publié par Maud Leuenberger. Maud est la rédactrice en chef du blog français de Shopify.

Texte original par Christopher Clunas. Traduction par Solenn Marchand. 

Sujets:

Développez votre entreprise avec le programme Partenaires Shopify

En savoir plus