Non, la documentation, c'est chiant, ça ne sert à rien si tu peux aller dans le code directement.
C'est un peu plus dur en bouche que la documentation, mais on défend vraiment le babybel face à un bon vieux maroilles ici ?
Alors que l'ananas sur la pizza, c'est le petit plus qui est corolaire au noyau, mais pas directement à l'intérieur du fruit.
Posté par steph1978 .
Évalué à 8 (+6/-0).
Dernière modification le 18 juin 2025 à 20:52.
Le code dit comment c'est fait.
La doc dit à quoi ça sert et comment l'utiliser
Une bonne doc c'est extrêmement plaisant à utiliser.
Des exemples qui me viennent : jq, sqlpage, jinja, python stdlib.
Une mauvaise doc c'est une doc qui se contente d'énumérer la liste des fonctions avec une description qui paraphrase le nom de la fonction.
J'ai trouvé un peu de ça dans les packages elixir ou python alors que j'adore programmer dans ces langages.
Le fait qu'il existe "une" documentation est déjà étrange. Souvent il y en a plusieurs, avec des objectifs différents.
Le manuel d'utilisation n'est pas la même chose que la référence des APIs ou que la documentation de l'architecture du code.
Selon le type de projet, tous ces documents n'ont pasforcément besoin d'exister. Peut-être qu'il n'y a pas d'utilisateurs (c'est le cas de certains de mes projets exploratoires). Peut-être qu'il n'y a pas d'API ou pas d'architecture.
Mais en général, "va voir dans le code", c'est pénible quand j'essaie d'utiliser le code de quelqu'un d'autre, qu'il n'y a aucune info sur ce que fait chaque fichier et dossier à part son nom, et que c'est écrit dans un langage de programmation que je ne connaìt pas.
Posté par uso (site web personnel) .
Évalué à 3 (+2/-0).
Dernière modification le 19 juin 2025 à 14:45.
Mais en général, "va voir dans le code", c'est pénible quand j'essaie d'utiliser le code de quelqu'un d'autre, qu'il n'y a aucune info sur ce que fait chaque fichier et dossier à part son nom, et que c'est écrit dans un langage de programmation que je ne connaìt pas.
Il n'y a pas longtemps, j'ai essayé d'intégrer kuroko a un projet perso, en tant que moteur de scripting.
Et si la doc explique comment appeler kuroko, pour intégrer tes struct C dans kuroko, c'est du gros RTFS, et peu être que ça aurais été plus simple avec une doc.
Mais maintenant que j'ai réussi à tout faire marcher comme je veux, est-ce qu'il n'est pas normal que mon syndrome de Stockholm, me force à dire que la documentation ne sert à rien, et à regarder avec mépris ce qui la demande ?
de la même manière que si on aime le fromage, on méprisse ce qui mange du kiri.
Et sinon pour revenir sur le sujet principal du lien, la pizza, la pizza historiquement, c'est le plat du pauvre, qui consiste à mettre les restes sur une pâte à pains, hors l'ananas, c'est un truc que l'on trouve pour pas cher dans un supermarché, ou t'a facilement une boite d'ananas en jus qui reste chez toi.
Alors que d'autre ingrédient comme la burrata ou le jambon à la truffe, eux, ne sont pas censés être dans la catégorie plat du pauvre.
Donc la truffe et la burrata, sont des trahisons bien plus grave que l'ananas à l'esprit de la pizza.
# non, c'est l'inverse
Posté par steph1978 . Évalué à 6 (+5/-1).
La documentation c'est pénible à faire et agréable à consommer.
L'ananas sur la pizza, c'est facile à faire et désagréable à consommer.
[^] # Re: non, c'est l'inverse
Posté par uso (site web personnel) . Évalué à 1 (+1/-1).
Non, la documentation, c'est chiant, ça ne sert à rien si tu peux aller dans le code directement.
C'est un peu plus dur en bouche que la documentation, mais on défend vraiment le babybel face à un bon vieux maroilles ici ?
Alors que l'ananas sur la pizza, c'est le petit plus qui est corolaire au noyau, mais pas directement à l'intérieur du fruit.
[^] # Re: non, c'est l'inverse
Posté par steph1978 . Évalué à 8 (+6/-0). Dernière modification le 18 juin 2025 à 20:52.
Le code dit comment c'est fait.
La doc dit à quoi ça sert et comment l'utiliser
Une bonne doc c'est extrêmement plaisant à utiliser.
Des exemples qui me viennent : jq, sqlpage, jinja, python stdlib.
Une mauvaise doc c'est une doc qui se contente d'énumérer la liste des fonctions avec une description qui paraphrase le nom de la fonction.
J'ai trouvé un peu de ça dans les packages elixir ou python alors que j'adore programmer dans ces langages.
[^] # Re: non, c'est l'inverse
Posté par pulkomandy (site web personnel, Mastodon) . Évalué à 7 (+4/-0).
Le fait qu'il existe "une" documentation est déjà étrange. Souvent il y en a plusieurs, avec des objectifs différents.
Le manuel d'utilisation n'est pas la même chose que la référence des APIs ou que la documentation de l'architecture du code.
Selon le type de projet, tous ces documents n'ont pasforcément besoin d'exister. Peut-être qu'il n'y a pas d'utilisateurs (c'est le cas de certains de mes projets exploratoires). Peut-être qu'il n'y a pas d'API ou pas d'architecture.
Mais en général, "va voir dans le code", c'est pénible quand j'essaie d'utiliser le code de quelqu'un d'autre, qu'il n'y a aucune info sur ce que fait chaque fichier et dossier à part son nom, et que c'est écrit dans un langage de programmation que je ne connaìt pas.
[^] # Re: non, c'est l'inverse
Posté par uso (site web personnel) . Évalué à 3 (+2/-0). Dernière modification le 19 juin 2025 à 14:45.
Il n'y a pas longtemps, j'ai essayé d'intégrer kuroko a un projet perso, en tant que moteur de scripting.
Et si la doc explique comment appeler kuroko, pour intégrer tes struct C dans kuroko, c'est du gros RTFS, et peu être que ça aurais été plus simple avec une doc.
Mais maintenant que j'ai réussi à tout faire marcher comme je veux, est-ce qu'il n'est pas normal que mon syndrome de Stockholm, me force à dire que la documentation ne sert à rien, et à regarder avec mépris ce qui la demande ?
de la même manière que si on aime le fromage, on méprisse ce qui mange du kiri.
Et sinon pour revenir sur le sujet principal du lien, la pizza, la pizza historiquement, c'est le plat du pauvre, qui consiste à mettre les restes sur une pâte à pains, hors l'ananas, c'est un truc que l'on trouve pour pas cher dans un supermarché, ou t'a facilement une boite d'ananas en jus qui reste chez toi.
Alors que d'autre ingrédient comme la burrata ou le jambon à la truffe, eux, ne sont pas censés être dans la catégorie plat du pauvre.
Donc la truffe et la burrata, sont des trahisons bien plus grave que l'ananas à l'esprit de la pizza.
Envoyer un commentaire
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.