La documentation !

Lors de nombreuse conférence et très souvent au travail, un point important revient tout le temps :

Les tests et la documentation !

Je m’attarde ici sur la seconde partie. En effet, nous passons beaucoup de temps à coder… Mais sans une bonne documentation, notre code n’est pas facilement compréhensible par les autres. Pour une bibliothèque, son utilisation sera faible si la documentation est faible. Pour une application, le code devient legacy très rapidement et personne ne voudra plus le modifier.

Mais que dire de la documentation du langage de programmation utilisé ? Je mets le langage dans la catégorie des bibliothèques. Ceux qui me connaissent un peu sauront que je parle de PHP et plus particulièrement de la traduction de la documentation en français.

Il y a quelque temps, j’ai posté un twit pour inviter les bonnes volontés à venir traduire la documentation.

Après 31 Re-Twit (merci à eux) et 12 j’aime, il y a eu 2 contributions. Le résultat n’est pas si mal !

Au fil de la pérégrination de mon twit, Antoile Bellion a posé une question à laquelle je m’attendais.

La réponse fut pertinente de la part de l’un des traducteurs de la documentation PHP :

Pour ma part, je me suis attaché à réaliser un peu de ménage dans les fichiers à mettre à jour. En effet, certains fichiers à mettre à jour ne comportaient aucune (ou très peux de) modification. Il en reste encore beaucoup, mais le compteur est aujourd’hui à 913.

Pour les nouveaux fichiers à traduire, il reste 1258 fichiers en attente d’une première traduction.

Et vous, pourrez-vous nous aider à rattraper la documentation française de PHP ?

Le guide du traducteur (Anglais) et l’éditeur en ligne.

2 réflexions au sujet de « La documentation ! »

  1. Concernant la doc de php, j’ai essayer, mais la barrière pour rentrer dans la doc php est tellement complexe et le suivit semble absent. Bref, cela ne donne pas du tout envie de contribuer. Ce qui est fort dommage.

    1. Bonjour Grummfy,

      Comme toute technologie, il y a un délai pour se l’approprier. Tu es bien placé pour le savoir
      Celle de la doc de PHP est basée sur le XML. Après nombre de modifications, je m’y suis fait et maintenant ça va vite.
      Le principe de noter la référence du fichier anglais dans le fichier traduit est pratique pour connaitre les changements sans les rechercher. D’autre part, il est techniquement possible de vérifier le nombre de balises présentes dans les deux langues pour signaler un problème de traduction. Dans ces cas, la patience est de mise et un bon logiciel de comparaison est très utile.

      Pour ce qui est des traducteurs, je ne sais pas où ils en sont avec PHP et sa documentation. Yannick semble avoir stoppé tout travail il y a 4 ou 5 mois environ.
      Comme pour tous projets, il est important que la relève soit assurée.

      Je me concentre plus sur la mise à jour des pages existantes que sur la traduction de nouvelle page. Il me semble plus important que les pages déjà traduites soient à jour.
      Si tu as des questions, je tenterai d’y répondre du mieux possible.

Laisser un commentaire

Votre adresse de messagerie ne sera pas publiée. Les champs obligatoires sont indiqués avec *