WordPress et la documentation

Lorsque vous recherchez de la documentation sur WordPress, votre réflexe est probablement de saisir le nom de la fonction PHP, du crochet (hook) ou de l’élément dont vous avez besoin sur votre moteur de recherche favori. Plusieurs sources sont alors proposées : les sources officieuses comme les articles de blogs, et les sources officielles. Elles sont simples à identifier puisqu’elles utilisent le domaine WordPress.org.

Deux types de sources officielles co-existent actuellement dans les résultats de recherche : l’ancien Codex, et DevHub.

Le codex c’est terminé, place à DevHub !

Depuis maintenant quelques années, une migration a été lancée vers la nouvelle plateforme de référence pour la documentation de WordPress : surnommée « DevHub », developer.wordpress.org a pour vocation de remplacer totalement l’ancien Codex.

Pourquoi changer ?

Basé sur un Wiki (une encyclopédie modifiable), le Codex avait l’avantage (et l’inconvénient) d’avoir un contenu intégralement généré par ses utilisatrices et utilisateurs.

Avantages, car il n’y avait pas de limite à la création de pages de documentation et cela permettait à tout un chacun de proposer des contributions, des exemples, etc.

Inconvénients, car il était alors quasiment impossible de maintenir à jour cette documentation. Les fonctionnalités de WordPress évoluent rapidement, au rythme de généralement 3 nouvelles versions majeures par an et une dizaine de versions mineures. Il est très difficile de tenir la documentation de ces fonctionnalités à jour avec quelques dizaines de volontaires. Ainsi, le Codex est condamné à une certaine obsolescence, le volume de contribution des nouvelles pages de documentation ne pouvant suivre le volume d’évolutions au sein du CMS.

DevHub, vers une documentation semi-automatisée

Au contraire du Codex, la nouvelle plateforme de référence DevHub – developer.wordpress.org – fonctionne de façon automatisée (ou presque).

Sur DevHub, la documentation des fonctions, crochets (hooks), filtres et autres actions est générée automatiquement à partir de la documentation présente dans les fichiers du cœur du CMS.
Cette documentation est donc toujours 100% à jour par rapport au cœur WP.

Pour le coup, l’avantage est clair : dès la sortie d’une nouvelle version de WordPress, l’ensemble de la documentation est automatiquement mis à jour pour intégrer les nouvelles fonctionnalités, comprenant les pages de documentation existantes comme la création de nouvelles pages pour les nouvelles fonctionnalités.

L’inconvénient que l’on peut y voir est un format plus rigide que l’ancien Codex. Même si cela a clairement des avantages en terme de rapidité de l’accès à l’information vu que tout est formaté de la même façon, cela aura peut-être pour certain·e·s un peu moins de charme que le bon vieux Codex et ses pages générées à l’huile de coude 🙂

Le codex progressivement redirigé vers DevHub

Les pages du Codex seront progressivement redirigées de façon permanente vers DevHub (c’est déjà le cas pour beaucoup d’entre elles). D’ici là, faites attention :

Les contenus du Codex ne sont plus maintenus et proposent donc une documentation incomplète ou obsolète.
Il est fortement recommandé d’utiliser la documentation proposée sur developer.wordpress.org qui est maintenant la seule documentation officielle de WordPress à jour.

Bien sûr, les pages du Codex étant progressivement redirigées vers DevHub, nous sommes dans une période de transition pendant laquelle les deux co-existent. Forts d’une grande notoriété, les pages du Codex apparaissent souvent avant les pages DevHub dans les résultats de recherche. Mais cela sera résolu au fur et à mesure de la redirection permanente des pages vers DevHub.

Comment lire une page de documentation sur DevHub

Prenons par exemple une fonction de base de WP au hasard : get_the_time().

Sur la fiche developer.w.org, on retrouvera plusieurs sections :

• Le nom de la fonction
• Une description courte
• Une description longue (quand c’est nécessaire)

• Les paramètres d’entrée de la fonction :

• Les éléments retournés par la fonction (si la fonction est sensée retourner quelque chose) :

• La source de la fonction dans le cœur WordPress, avec les éléments suivants :
  • Le fichier dans lequel la fonction est déclarée (lien cliquable vers la liste de toutes les fonctions déclarées dans ce fichier).
  • Le code de la fonction.
  • Un bouton permettant de voir le code source en entier.
  • Un lien « View on Trac » pour voir la fonction au sein du fichier où elle est déclarée sur Trac, sur le dépôt du code source de WordPress.

• Le changelog : il s’agit de la liste des différentes modifications faites sur la fonction et de la version de WordPress correspondant à chaque modification. Cela permet de savoir quand une fonction a été introduite dans le cœur WP et quand est-ce qu’elle a été modifiée.

• Une section Related composée de deux sous-sections :
  • Uses : les autres fonctions utilisées par la fonction en question
  • Used by : les autres fonctions qui utilisent la fonction en question

• Des User contributed notes : des sortes de commentaires permettant aux développeur·euse·s de proposer des exemples d’utilisation et autres remarques concernant la fonction.

Contribuer à la documentation de WordPress sur DevHub

N’hésitez pas à proposer des user contributed notes !

D’une part c’est un excellent moyen de contribuer à WordPress, d’autre part vous serez peut-être content de retrouver votre propre exemple ou remarque la prochaine fois que vous chercherez de la documentation sur cette fonction !

Les user contributed notes sont validées manuellement par l’équipe de documentation de WordPress.

Des questions ?

Si vous utilisez le Slack WordPress-fr, n’hésitez pas à poser vos questions dans le canal #documentation-fr (pour vous inscrire gratuitement, c’est par ici). Sinon, vous pouvez utiliser le forum d’entraide de l’association WPFR ou encore tout simplement publier un commentaire sur le présent article (modération a priori) 🙂

« Attends une minute… mais c’est tout en anglais DevHub ! »

Oui… 😊

…pour l’instant ! L’équipe de développement du réseau de sites WordPress.org a mis en place un outil permettant à chacune des 192 langues (!) dans lesquelles WordPress est traduit de proposer leur propre traduction de la documentation de WordPress.

Cet outil est en cours de test et le site français (fr.wordpress.org) sera parmi les premiers à disposer de cet outil. Nous sommes actuellement en train de finaliser les préparatifs. L’équipe de documentation de WP en français devrait pouvoir commencer son travail d’ici quelques semaines/mois. Bien entendu, il s’agit d’un travail de longue haleine et toutes les bonnes volontés seront les bienvenues !