> Il est clair que mettre en place une documentation est assez fastidieux, cependant si celle-ci est faite en même temps que le développement c'est beaucoup moins contraignant. Un peu de rigueur dans la mise à jour et on s'y retrouve. Certes, les projets avancent un peu moins vite mais parfois ce n'est pas plus mal .... entre avoir une bibliothèque inutilisable parce que non documentée ou doc pas à jour, et une bibliothèque qui évolue moins vite mais qui est bien documentée, je choisis la deuxième ....
C'est aussi une question de volume. Pour un projet qui démarre en mono-développeur, ou qui est ambitieux avec trop peu de personnes, ou qui ne bénéficie pas d'une personne qui aime / sait organiser une doc, c'est inutilement handicapant. Dans ce genre de configuration, il vaut mieux (à mon avis, que je partage) partir à l'aventure, faire quelque chose de fonctionnel et imparfait, en retirer des leçons pour le futur, et faire un tant soit peu de commentaires dans le code et de doc intégrée.
Je prends un exemple (que j'aime vraiment pratiquer) : Ruby. La clarté du langage aide à commenter peu en conservant une bonne lisibilité (du moment qu'on évite de coder à la perl ou à la C). Dans ce cas, cependant, l'ouverture et la lecture du code rebutant toujours le débutant, il est positif de temps en temps de faire une explication pour débutants sur un site du projet, mais overkill et épuisant de faire une documentation exhaustive de tous les cas possibles.
> Loin de moi l'idée de trouver un coupable, simplement je déplore un état de fait. Et surtout, il y a encore des développeurs qui s'imaginent que le code source suffit, et qu'il n'y a pas besoin de documentation. Et c'est entre autre pour ça qu'en entreprise les LL se trainent une maivaise image.
>
> C'est une vision utopique du dev de LL.
Oui, enfin, en même temps, prendre les entreprises en exemple, c'est plutôt utopique aussi. Ce que j'ai beaucoup vu en SSII c'est :
- on ne factorise pas, ça ne sert à rien parce qu'on repars à 0 à chaque projet (nouvelles équipes constituées de bric et de broc, pas de phase d'analyse reposant sur des projets précédents, pas d'auto-formation digne de ce nom en interne, ...)
- c'est bien de faire des commentaires, mais avec les deadlines et tout ils sautent (et on récompense surtout le gars qui "pond de la ligne" et pas vraiment le gars qui réfléchit et propose des idées élégantes pour gagner du temps et de l'efficacité)
- la conception est un bon gros bloc de marbre gravé par un architecte, architecte qui est va sur un autre projet pendant la phase de réalisation
- la documentation livrée au client n'est pas à jour, pleine de répétitions de points e détails et de trous sur des choses essentielles pour comprendre le fonctionnement général, etc.
Non, la raison principale pour laquelle le LL a mauvaise presse devant une entreprise, c'est surtout parce que :
- on ne le paye pas (en licences) et que tout ce qui n'est pas cher est suspect de ne pas fonctionner
- c'est un royaume de bidouilleurs et tout ce qui se bidouille c'est pas fiable
- on n'a personne à attaquer en justice ou sur lequel faire pression quand on n'est pas content sinon soi-même
Ceci étant dit, il y a énormément d'entreprises qui commencent ou continuent à faire confiance aux les LL, en tête les hébergeurs (les serveurs qui coûtent pas cher, c'est bien quand on cause à des clients qui n'ont pas de très gros budgets mais qui sont nombreux), les SSII (houlà, crise financière tout ça, maintenant ça coûte cher une licence WebSphere, pfouuuu), et les startups (qui étaient déjà convaincues de toute façon, puisque pour bien démarrer une start-up, coût de licence zéro c'est mieux).
>> Il est impossible pour une tierce personne de déveopper une doc à jour pour du LL, sans mettre les développeurs dans la boucle, car le développement des LL va bien trop vite.
C'est peut-être parce que tu raisonnes trop en doc au forfait (une seule livraison finale, une seule grosse doc finale).
Je vais prendre un autre exemple Ruby : Rails. La doc de base est extrêmement bien faite (au point que je pioche dedans avant de chercher des tutoriaux), et n'a pas besoin de changer radicalement fréquement, mais la collaboration est encouragée (entre autres par l'utilisation d'un dépôt git publique et la possibilité d'envoyer des patchs de documentation).
Bien sûr, tôt ou tard les développeurs doivent être dans la boucle, mais il ne faut pas leur demander d'assurer tout le travail de documentation quel que soit le projet, sinon le développeur, il s'étiolle.
[^] # Re: Wiki-libra?
Posté par Bastes . En réponse au journal Documentation collaborative. Évalué à 4.
C'est aussi une question de volume. Pour un projet qui démarre en mono-développeur, ou qui est ambitieux avec trop peu de personnes, ou qui ne bénéficie pas d'une personne qui aime / sait organiser une doc, c'est inutilement handicapant. Dans ce genre de configuration, il vaut mieux (à mon avis, que je partage) partir à l'aventure, faire quelque chose de fonctionnel et imparfait, en retirer des leçons pour le futur, et faire un tant soit peu de commentaires dans le code et de doc intégrée.
Je prends un exemple (que j'aime vraiment pratiquer) : Ruby. La clarté du langage aide à commenter peu en conservant une bonne lisibilité (du moment qu'on évite de coder à la perl ou à la C). Dans ce cas, cependant, l'ouverture et la lecture du code rebutant toujours le débutant, il est positif de temps en temps de faire une explication pour débutants sur un site du projet, mais overkill et épuisant de faire une documentation exhaustive de tous les cas possibles.
> Loin de moi l'idée de trouver un coupable, simplement je déplore un état de fait. Et surtout, il y a encore des développeurs qui s'imaginent que le code source suffit, et qu'il n'y a pas besoin de documentation. Et c'est entre autre pour ça qu'en entreprise les LL se trainent une maivaise image.
>
> C'est une vision utopique du dev de LL.
Oui, enfin, en même temps, prendre les entreprises en exemple, c'est plutôt utopique aussi. Ce que j'ai beaucoup vu en SSII c'est :
- on ne factorise pas, ça ne sert à rien parce qu'on repars à 0 à chaque projet (nouvelles équipes constituées de bric et de broc, pas de phase d'analyse reposant sur des projets précédents, pas d'auto-formation digne de ce nom en interne, ...)
- c'est bien de faire des commentaires, mais avec les deadlines et tout ils sautent (et on récompense surtout le gars qui "pond de la ligne" et pas vraiment le gars qui réfléchit et propose des idées élégantes pour gagner du temps et de l'efficacité)
- la conception est un bon gros bloc de marbre gravé par un architecte, architecte qui est va sur un autre projet pendant la phase de réalisation
- la documentation livrée au client n'est pas à jour, pleine de répétitions de points e détails et de trous sur des choses essentielles pour comprendre le fonctionnement général, etc.
Non, la raison principale pour laquelle le LL a mauvaise presse devant une entreprise, c'est surtout parce que :
- on ne le paye pas (en licences) et que tout ce qui n'est pas cher est suspect de ne pas fonctionner
- c'est un royaume de bidouilleurs et tout ce qui se bidouille c'est pas fiable
- on n'a personne à attaquer en justice ou sur lequel faire pression quand on n'est pas content sinon soi-même
Ceci étant dit, il y a énormément d'entreprises qui commencent ou continuent à faire confiance aux les LL, en tête les hébergeurs (les serveurs qui coûtent pas cher, c'est bien quand on cause à des clients qui n'ont pas de très gros budgets mais qui sont nombreux), les SSII (houlà, crise financière tout ça, maintenant ça coûte cher une licence WebSphere, pfouuuu), et les startups (qui étaient déjà convaincues de toute façon, puisque pour bien démarrer une start-up, coût de licence zéro c'est mieux).
>> Il est impossible pour une tierce personne de déveopper une doc à jour pour du LL, sans mettre les développeurs dans la boucle, car le développement des LL va bien trop vite.
C'est peut-être parce que tu raisonnes trop en doc au forfait (une seule livraison finale, une seule grosse doc finale).
Je vais prendre un autre exemple Ruby : Rails. La doc de base est extrêmement bien faite (au point que je pioche dedans avant de chercher des tutoriaux), et n'a pas besoin de changer radicalement fréquement, mais la collaboration est encouragée (entre autres par l'utilisation d'un dépôt git publique et la possibilité d'envoyer des patchs de documentation).
Bien sûr, tôt ou tard les développeurs doivent être dans la boucle, mais il ne faut pas leur demander d'assurer tout le travail de documentation quel que soit le projet, sinon le développeur, il s'étiolle.