La plupart de temps, ce qui m'agace c'est de lire de la mauvaise documentation. Voici les principales défauts que je retrouve dans les documentations avec lesquelles je dois le plus souvent travailler:
Documentation qui hésite entre la référence, l'introduction du manuel de l'utilisateur et le manuel de l'utilisateur lui-même. L'information y est mal structurée, pas au bon endroit, etc.
La documentation mal présentée, l'exemple typique est la documentation de NodeJS ou celle de l'API AWS JavaScript. La documentation n'est pas assez espacée, pas assez bien structurée – on a des descriptions d'éléments 'APIs obsolètes qui s'étendent sur plusieurs écrans au beau milieu de la description, et comme il n'y a pas d'espaces verticaux ou de mises en retrait bien visibles, on ne se s'y retrouve pas. À la rigueur le seul moyen de s'en sortir à peu près, serait de l'imprimer! Et puis comme on est en 2016 le concept de page est has been et on écrit tout dans un seul document – alors que la page est une bonne unité pour délimiter et hiérarchiser le texte.
La documentation ambigüe, où les descriptions des fonctions laissent place non pas à une interprétation possible mais à plusieurs, ou bien qui laissent en suspens des questions essentielles que tout programmeur expérimenté se pose dans certaines situations. Par exemple la documentation du SDK AWS n'arrive pas à traiter proprement les cas de "valeur", "null" et "membre non défini" – alors que quand on documente du JavaScript, c'est évidemment la chose avec laquelle il faut être le plus propre! – ce qui oblige à faire des essais. Autre exemple la documentation de NodeJS qui, lorsqu'elle aborde les streams se garde bien de décrire, lorsqu'on utilise des streams lisant la sortie d'un processus fils, le comportement bloquant ou non de l'écriture par le processus fils. Quand on lit en détails on peut deviner ce qui se passe et essayer pour vérifier, mais ce ne devrait pas être nécessaire.
La documentation bavarde, qui au lieu d'utiliser une langue technique claire et concise se livre à des bavardages incessants. Exemple typique le manuel de GNU Make qui arrive à dire en plus de 205 pages essentiellement la même chose que les 8 pages de man du BSD Make. Pour moi c'est beaucoup plus facile de retrouver une information dans 8 pages de documentation que dans 205.
# Lire la documentation
Posté par Michaël (site web personnel) . En réponse au sondage Ce que je déteste le plus en informatique / programmation / codage c'est... :. Évalué à 10.
La plupart de temps, ce qui m'agace c'est de lire de la mauvaise documentation. Voici les principales défauts que je retrouve dans les documentations avec lesquelles je dois le plus souvent travailler:
Documentation qui hésite entre la référence, l'introduction du manuel de l'utilisateur et le manuel de l'utilisateur lui-même. L'information y est mal structurée, pas au bon endroit, etc.
La documentation mal présentée, l'exemple typique est la documentation de NodeJS ou celle de l'API AWS JavaScript. La documentation n'est pas assez espacée, pas assez bien structurée – on a des descriptions d'éléments 'APIs obsolètes qui s'étendent sur plusieurs écrans au beau milieu de la description, et comme il n'y a pas d'espaces verticaux ou de mises en retrait bien visibles, on ne se s'y retrouve pas. À la rigueur le seul moyen de s'en sortir à peu près, serait de l'imprimer! Et puis comme on est en 2016 le concept de page est has been et on écrit tout dans un seul document – alors que la page est une bonne unité pour délimiter et hiérarchiser le texte.
La documentation ambigüe, où les descriptions des fonctions laissent place non pas à une interprétation possible mais à plusieurs, ou bien qui laissent en suspens des questions essentielles que tout programmeur expérimenté se pose dans certaines situations. Par exemple la documentation du SDK AWS n'arrive pas à traiter proprement les cas de "valeur", "null" et "membre non défini" – alors que quand on documente du JavaScript, c'est évidemment la chose avec laquelle il faut être le plus propre! – ce qui oblige à faire des essais. Autre exemple la documentation de NodeJS qui, lorsqu'elle aborde les streams se garde bien de décrire, lorsqu'on utilise des streams lisant la sortie d'un processus fils, le comportement bloquant ou non de l'écriture par le processus fils. Quand on lit en détails on peut deviner ce qui se passe et essayer pour vérifier, mais ce ne devrait pas être nécessaire.
La documentation bavarde, qui au lieu d'utiliser une langue technique claire et concise se livre à des bavardages incessants. Exemple typique le manuel de GNU Make qui arrive à dire en plus de 205 pages essentiellement la même chose que les 8 pages de man du BSD Make. Pour moi c'est beaucoup plus facile de retrouver une information dans 8 pages de documentation que dans 205.