Documentation des plugins et thèmes WordPress

La documentation est quelque chose qui n'est généralement apprécié que lorsqu'il y a un problème et que vous avez besoin de réponses rapidement. Dans cet article, nous passerons en revue les raisons pour lesquelles la rédaction de documentation pour vos actifs WordPress est importante pour votre pratique en tant que développeur WordPress et la qualité des thèmes et plugins que vous proposez.

Pourquoi la documentation est-elle importante ?

Il est important de conserver une documentation à jour sur vos projets, actifs ou produits pour de nombreuses raisons.

Tout d'abord, c'est une expérience courante de regarder quelque chose que vous avez fait il y a 2 mois et que vous n'avez pas touché depuis, et de n'avoir aucune idée de ce que cela signifie. Lorsque vous le développez, vous avez tout dans votre tête, mais cette compréhension ne sera plus là à l'avenir. Ainsi, soit en utilisant des commentaires de code en ligne, soit en écrivant des notes en texte brut dans Markdown, vous éviterez toute confusion.

Deuxièmement, garder vos actifs documentés est utile pour les autres développeurs WordPress. Et cela a du sens même si vous êtes un indépendant indépendant (vous êtes obligé de collaborer avec d'autres personnes à un moment donné). Ils devront soit utiliser ces actifs, soit être invités à les maintenir et/ou à les mettre à jour. Il est très frustrant d'avoir à utiliser du code non documenté qui est écrit par quelqu'un d'autre, qui n'est pas là pour fournir une assistance ou expliquer certains éléments difficiles.

Enfin, la documentation ajoute un aspect « raffiné » à vos produits et vos clients vous aimeront davantage.

5 principes pour une documentation efficace

La rédaction technique est une discipline à part entière et elle est utilisée pour communiquer des informations techniques de manière claire et sans ambiguïté. (Non limité aux seuls ordinateurs, les avocats et les médecins, par exemple, utilisent également leur propre langage technique). Pour cette raison, un document considéré comme une rédaction technique suit généralement un certain style et obéit à un ensemble de règles.

Passons en revue les 5 plus importants pour que vous puissiez rédiger une documentation efficace pour vos produits !

• Préférez utiliser moins de mots que vous n'en utiliseriez normalement dans votre écriture : chaque mot doit avoir un but. Soyez direct et simple. La documentation est généralement recherchée lorsqu'une personne est en difficulté et souhaite trouver rapidement une solution. Par exemple, une phrase telle que "L'échec de la destruction de l'objet Q entraînera des fuites de mémoire" est préférable à "L'échec de la destruction de l'objet Q entraînera l'introduction de fuites de mémoire".
• Préférez utiliser la voix active plutôt que passive : « Cliquez sur le bouton en haut à droite » au lieu de « Il faut cliquer sur le bouton en haut à droite ». L'utilisation d'une voix active efface toute ambiguïté sur qui fait quoi. La voix passive n'est utilisée que lorsque vous devez vous concentrer sur l'objet plutôt que sur le sujet (par exemple, la plate-forme de Pressidium est conçue dans un souci de sécurité ) .
• Utilisez un langage descriptif lorsque vous devez décrire des concepts et impératif lorsque vous devez décrire une procédure étape par étape (comme des didacticiels).
• Utilisez des listes à puces lorsque vous devez répertorier des éléments sans ordre et des listes numérotées lorsque l'ordre des points est important.
• Assurez-vous d'avoir testé vous-même les instructions avant de les présenter !

Documentation des plugins WordPress

Les plugins WordPress sont comme n'importe quel autre logiciel. Ils fournissent une certaine fonctionnalité, ils nécessitent une installation et parfois un dépannage également. Peu importe leur simplicité, il est toujours bon de fournir une documentation adéquate, car tous les utilisateurs ne partagent pas la même expertise technique.

Hébergez votre site web avec Pressidium

GARANTIE DE REMBOURSEMENT DE 60 JOURS

VOIR NOS FORFAITS

La publication de votre plugin WordPress sur wordpress.org vous fournira un endroit pour mettre des instructions d'installation, des captures d'écran, une FAQ et même un Changelog ! Les remplir avec des informations utiles et de qualité est essentiel pour rendre votre plugin plus populaire :

• Rédigez une description convaincante et utile qui incitera l'utilisateur à télécharger votre plugin et à visiter votre site Web.
• Ajoutez des captures d'écran annotées expliquant chaque élément de configuration de votre plugin en plus de celles montrant à quoi ressemble votre plugin dans le navigateur.
• Posez des questions dans la FAQ qui ne sont pas banales. Un bon moyen de découvrir des cas extrêmes étranges est de demander à un ami non averti en informatique d'utiliser votre plugin.
• Ayez un journal des modifications mis à jour et bien écrit. Les one-liners laconiques et énigmatiques sont un grand non-non et montrent que vous ne vous souciez pas vraiment de vos utilisateurs.
• Assurez-vous que le code de votre plugin est bien commenté et suit les meilleures pratiques logicielles et les normes de codage officielles.

Si vous êtes bloqué et avez besoin d'inspiration, effectuez une petite recherche et voyez comment le texte est écrit dans les plugins populaires qui ont des centaines de milliers d'installations, par rapport aux moins utilisés.

Documentation des thèmes WordPress

Documenter les thèmes WordPress est une tout autre affaire. Le problème le plus courant avec les thèmes WordPress est de ne pas savoir quelle section correspond à quel élément visuel. Tout le monde ne maîtrise pas le CSS :

• Créez une hiérarchie de toutes les sections de votre CSS, avec les descriptions correspondantes.
• Pour chaque section, ajoutez une capture d'écran annotée détaillant chaque fonctionnalité, ainsi qu'un petit exemple. N'oubliez pas d'utiliser la voix active et le langage impératif lorsque vous montrez comment faire quelque chose qui nécessite que l'utilisateur suive des instructions.
• Utilisez un outil tel que css_doc pour vous aider. Cela génère un style de documentation JavaDoc et peut être publié.
• Parfois, les commentaires de code ne suffisent pas et vous devez créer un document Guide de style pour votre thème CSS. Les documents de guide de style 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. Voir cet exemple de Google.
• Utilisez un framework CSS comme Blueprint CSS. Cela vous aidera dans le développement en vous fournissant un ensemble d'outils tels qu'une grille personnalisable, une typographie par défaut qui fonctionne, la réinitialisation du CSS du navigateur et bien plus encore.
• Encore une fois, n'oubliez pas de consulter les normes de codage CSS officielles de WordPress.