Documentation produit pour les professionnels de WordPress

La documentation du produit est généralement considérée comme sans importance, que vous pouvez couper les coins ronds. Il n'est pas considéré comme quelque chose qui peut offrir de la valeur au client, ou comme quelque chose qui pourrait éventuellement affecter des domaines commerciaux clés tels que les revenus et le marketing. Certes, en tant que professionnel de WordPress, vous n'aurez pas besoin d'écrire de la documentation de la même manière qu'Atlassian ou Cisco. Habituellement, lorsque les gens pensent à la « documentation », ils évoquent des images de manuels d'utilisation épais et imprimés, indexés par ordre alphabétique sur une très grande étagère que personne ne lit jamais.

Mais cela a changé :

Avec l'avènement d'Agile et de DevOps, la livraison de logiciels est devenue plus rapide et le cycle de développement est également devenu plus dynamique. Et par conséquent, la documentation reflète désormais l'état actuel de la dernière version, au lieu d'être quelque chose de statique écrit sur papier pour toujours. La documentation est intégrée au cycle de développement et est mise à jour aussi fréquemment que les logiciels.

Pourquoi les professionnels de WordPress devraient-ils se soucier de la documentation produit ?

Une documentation utile et à jour facilite non seulement la vie de vos utilisateurs, mais ajoute également un niveau de finition qui devient un atout marketing sans pareil. Inversement, une mauvaise documentation a un impact négatif. Vous en avez probablement fait l'expérience vous-même : vous avez eu un problème pour lequel vous vous efforciez de trouver la solution dans la documentation et quand vous ne l'avez pas fait, vous vous êtes retrouvé frustré (et probablement en colère). Cela ne fait qu'empirer si vous payez pour le produit.

Si vous travaillez dans une agence WordPress, fournir de la documentation dans tous les domaines d'un projet, de la conception initiale aux actifs, ajoutera un niveau de professionnalisme montrant que :

1. Vous faites attention aux détails.
2. Vous vous souciez suffisamment de votre client pour faire un effort supplémentaire.
3. Vous êtes transparent et confiant quant à vos décisions de conception et de projet technique.

Mike Puterbaugh, vice-président du marketing chez MindTouch a écrit un article Mashable décrivant les 5 raisons pour lesquelles la documentation de votre produit est un atout marketing. Il a conclu par ce qui suit :

Ce n'est pas une entreprise sexy, mais cela vous fera gagner le respect de vos pairs, une gestion d'entreprise plus efficace et une équipe plus collaborative. Parce qu'il ne s'agit pas de ce trimestre ou de cette année, mais plutôt d'affecter l'avantage concurrentiel et la croissance à long terme.

Maintenant que nous avons établi suffisamment de motivation, nous allons :

1. Explorez les différents types de documentation produit pertinents pour WordPress.
2. Discutez des besoins de chaque type de documentation et offrez des conseils pratiques.
3. Offrez quelques conseils initiaux sur la façon dont vous pouvez planifier et collaborer sur la documentation du produit. Surtout si vous travaillez dans une agence WordPress.

Types de documentation de produit WordPress

Un produit WordPress ne concerne pas seulement les plugins et les thèmes. Dans cette section, nous discuterons également de l'aide en ligne, des API REST et d'une chose curieuse appelée microcontenu.

Plugins WordPress

La documentation du plugin WordPress doit répondre à deux groupes : les utilisateurs et les développeurs. Les besoins de documentation de chacun sont différents, tout comme le style d'écriture utilisé.

Hébergez votre site web avec Pressidium

GARANTIE DE REMBOURSEMENT DE 60 JOURS

VOIR NOS FORFAITS

Utilisateurs

Les besoins de documentation des utilisateurs tournent principalement autour du dépannage et de la configuration. Ajoutez à cela que vous devez présenter votre plugin de manière attrayante afin d'inciter les utilisateurs à l'essayer. Chaque plugin a sa propre page sur le marché des plugins WordPress. Gardez à l'esprit les points suivants :

• Rédigez une description convaincante et utile qui encourage le téléchargement et l'utilisation.
• Ajoutez des captures d'écran annotées à partir de la page de configuration de votre plug-in Dashboard avec des descriptions.
• Posez des questions dans la FAQ qui sont utiles et non banales.
• Ayez un journal des modifications mis à jour et bien écrit. N'y ajoutez pas de notes énigmatiques ou concises.

Vous devez vous rappeler que lorsque les utilisateurs utilisent la documentation, ils sont probablement pressés et anxieux de trouver une solution. Rédigez de manière claire, simple et concise. Ne leur rendez pas la tâche plus difficile qu'elle ne l'est déjà.

Développeurs

En plus de suivre les meilleures pratiques logicielles et les normes de codage PHP officielles, vous devez concentrer votre attention sur les domaines suivants :

crochets de plug-in

Ceux-ci font le travail de modification du comportement de WordPress. Très probablement, votre plugin WordPress les utilise. Étant donné que les crochets de plugin sont une partie importante du code, vous devez documenter comment vous les utilisez et dans quelles fonctions WordPress ils sont impliqués.

balises de modèle

Les balises de modèle sont un autre moyen pour un plugin WordPress d'améliorer les fonctionnalités. Documentez les fonctions de balise de modèle que vous avez écrites. Incluez des exemples de la manière dont d'autres utilisateurs ou développeurs peuvent utiliser les balises sur leur site WordPress.

choix

Les options sont un moyen de stocker des informations particulières dans une base de données WordPress. Cela se fait via les fonctions add_option et get_options. Dans ce cas, documentez les paramètres que vous transmettez à ces fonctions.

base de données

Les plugins lisent et écrivent fréquemment beaucoup de choses différentes à partir d'une base de données. Comme il s'agit d'opérations fondamentales, les documenter aidera grandement les autres développeurs à comprendre le fonctionnement de votre plugin.

Thèmes WordPress

Il existe deux domaines différents dans lesquels vous pouvez créer une documentation pour les thèmes. Le premier est les fichiers source. Les fichiers CSS commentés sont plus faciles à comprendre et à lire que ceux qui n'en ont pas. Utilisez un outil tel que css_doc pour vous aider. Cela génère un style de documentation JavaDoc et il peut être publié :

L'autre domaine est les guides de style. Ces documents décrivent à quoi les éléments doivent ressembler et dans quels cas ils doivent être utilisés. Ils renforcent la cohérence et facilitent également la collaboration. Vous pouvez lire l'article de Hubspot sur les 20 superbes exemples de guides de style de marque, car il contient de nombreux exemples intéressants.

Encore une fois, n'oubliez pas de consulter les normes de codage CSS officielles de WordPress.

Documenter les éléments de conception avec autant de détails aide également à l'intégration de nouveaux employés si vous êtes une agence WordPress. Les guides de style peuvent être utilisés comme tutoriels ou matériel de référence pour les travaux nouveaux et passés des clients.

Aide en ligne

Étant donné que l'aide en ligne vise à résoudre un problème utilisateur particulier, commencer par une liste de tâches et de problèmes courants est la voie à suivre. Bien que la liste ne soit pas exhaustive au début, prenez le temps de produire autant d'éléments concrets que possible. L'idée est d'écrire un fichier d'aide en ligne pour chacune de ces tâches et problèmes, et de les lier aux informations connexes. Vous pouvez créer des parcours d'utilisateurs pour tracer les différents chemins qu'un utilisateur peut emprunter et effectuer au sein de votre application. Plonger dans les e-mails d'assistance pour remarquer les questions courantes et les zones problématiques est un bon moyen de garder votre base de connaissances à jour et utile.

Barry J. Rosenberg, auteur de Spring into Technical Writing propose les conseils suivants pour rédiger de bons fichiers d'aide :

Gardez chaque fichier d'aide aussi bref que possible. Préférez les listes numérotées aux listes à puces. Ne faites pas de digression, ne faites pas de note de bas de page et ne voulez pas. Gardez chaque fichier d'aide concentré sur une seule tâche discrète.

Microcontenu

Le microcontenu a deux définitions : la première étant un contenu comme les titres et les sections que les utilisateurs parcourent, afin d'obtenir l'essentiel d'un article particulier. Le second est de petits morceaux de contenu qui peuvent se suffire à eux-mêmes et sont utilisés pour améliorer l'expérience utilisateur. Un excellent exemple particulier que nous avons à l'esprit est le bit "plusieurs personnes sont en train de taper..." de Slack. (bien que Slack regorge de microcontenus parfaitement écrits).

Ce bit est déclenché lorsque plus de 3 personnes tapent simultanément dans le même canal. Au lieu de simplement imprimer une liste de personnes qui tapent actuellement, Slack prend cette information ennuyeuse et y ajoute du plaisir. La discussion commence à devenir vraiment chaude, et ça se voit. C'est un excellent exemple de la façon dont la documentation du produit (les messages d'application en font partie, non ?) fait parler de vous (et crée des mèmes hilarants comme ci-dessus).

API REST

La documentation des API REST est un art à part entière. Comme pour toute rédaction technique, vous devez viser la concision, la clarté et la simplicité dans les définitions. Étant donné que les API REST ont leur propre format et leurs propres complexités, vous ne pourriez pas faire pire que d'étudier l'excellent guide de documentation des API de Tom Johnson sur son blog I'd Rather Be Writing.

Collaborer et planifier la documentation

En fin de compte, la documentation devrait faire partie de la conception du produit. En tant que tel, vous devez l'aborder comme ayant un pipeline supplémentaire dans votre cycle logiciel. Cela signifie utiliser des référentiels de logiciels pour stocker la version de documentation la plus récente, utiliser des outils de suivi des bogues/problèmes pour surveiller les tâches et les problèmes, inclure la planification du projet de documentation dans votre feuille de route et, enfin et surtout, collaborer avec d'autres personnes. Un aperçu de la façon de commencer pourrait être le suivant :

1. Enregistrez tout ce que l'utilisateur voudrait savoir, ainsi que les zones pour lesquelles vous devrez écrire du texte.
2. Une fois que vous avez tout, regroupez-les en catégories et formez les titres des documents.
3. Rédigez une spécification pour chaque document détaillant des éléments tels que le titre, la description, le public cible, les médias (quelle forme aura le document), la longueur, le temps que cela prendra, etc.
4. Ajoutez les estimations des spécifications de la documentation à votre planification de projet.

Étant donné que la documentation produit couvre tous les domaines, il est presque certain que vous devrez travailler avec différentes personnes au sein de l'organisation. C'est une bonne idée de s'asseoir et de s'entendre sur une sorte de processus sur la façon dont tout cela se déroulera. Comme dans tout projet, vous devez identifier les parties prenantes qui fourniront une assistance technique, ainsi que celles qui réviseront et modifieront les modifications.

Hébergez votre site web avec Pressidium

GARANTIE DE REMBOURSEMENT DE 60 JOURS

VOIR NOS FORFAITS

Il devrait y avoir différentes étapes du processus. Ceux-ci devraient indiquer où les informations sont recueillies, quand le document est écrit, quand il est prêt pour la relecture littéraire, pour les commentaires techniques, la publication, etc. Insistez sur la différence entre les commentaires littéraires, techniques et liés au contenu. Par exemple, ce n'est pas vraiment utile lorsque vous demandez à un chef d'équipe de commenter votre document et qu'au lieu d'informations techniques, vous obtenez des cris de grammaire et de ponctuation.

Fermeture

La documentation produit est un atout qui s'avère payant à long terme. Cela donne de la valeur à votre client. Il pourrait même être si bon, comme la documentation de l'API de Stripe par exemple, que les gens en raffolent dans les forums. Cela renforce l'engagement et fait la publicité de votre marque et de votre produit de manière naturelle et puissante. Lorsqu'il est associé à un microcontenu créatif, il réalise ce que Mike Puterbaugh veut dire lorsqu'il dit que la documentation produit est « l'arme secrète du marketing ».