Bonjour cher journal,
ça fait un moment que je ne t'ai pas écrit, mais aujourd'hui, j'ai besoin de ton avis sur une idée qui me taraude.
On ne peut pas le nier, le monde du libre regorge de librairies très complètes qui répondent souvent à des problèmes pointus, et permettent de gagner un temps fou en développement.
Cependant, un des freins à la diffusion de certaines librairies auprès de développeurs pressés ou peu désireux de lire du code source toute la journée est le manque de documentation.
Bien sûr, l'incontournable doxygen permet de générer des documentations complètes, on peut aussi noter les efforts faits en programmation lettrée. Cependant, si ces outils sont pratiques, ils nécessitent un effort important de la part du développeur, ou l'implication forte d'utilisateurs. Ce mode de fonctionnement est souvent centralisé (du moins l'intégration au gestionnaire de version est possible par une petite poignée de participants), et ne facilite pas la participation massive des utilisateurs.
Or dans d'autres domaines, par exemple le domaine de la traduction ou de la rédaction de manuels, les outils en ligne collaboratifs commencent à faire légion. Il est alors surprenant de n'avoir pas rencontré jusqu'ici d'outil de documentation doxygen collaborative.
Cher journal, imagine l'outil suivant :
- il s'appuierait sur une interface web collaborative, où chacun pourrait améliorer la description des différentes fonctions d'une librairie
- il permettrait, par exemple à l'aide d'un jeu de couleurs (rouge, orange, vert) de mesurer l'avancée et la qualité de la documentation de la librairie
- il proposerait l'intégration automatique des commentaires au code source initial, suivant la syntaxe doxygen (ou tout autre format plus pertinent que tu connaîtrais, cher journal).
Les intérêts seraient multiples, puisque ça rendrait plus simple d'accès la participation à un projet, l'aspect collaboratif permettant aux moins sûrs d'entre nous d'apporter leur pierre, il élargirait ainsi le nombre d'intervenants et permettrait de converger vers une documentation développeur de qualité.
Alors, journal, tu connais des projets qui proposent ce genre d'outil ? Pour ma part, je n'en connais pas.
Journal Documentation collaborative
24
fév.
2009
# librairie ?
Posté par BAud (site web personnel) . Évalué à 4.
Vu que c'est ce que permet de documenter efficacement Doxygen ;-)
[^] # Re: librairie ?
Posté par jm trivial (site web personnel) . Évalué à 1.
[^] # Re: librairie ?
Posté par vermillon . Évalué à 2.
À mon avis, en informatique, ce que l'on appelle librairie / bibliothèque ne contient pas de livres (libr- / biblio-), alors pourquoi l'un des deux termes serait-il faux, le terme étant détourné de son sens d'origine?
De plus, le mot library en anglais vient bien sûr du français (ou du latin si l'on veut remonter plus loin), en quoi est-ce alors un anglicisme?
[et navré pour le HS]
[^] # Re: librairie ?
Posté par windu.2b . Évalué à 6.
Là-dessus, tout le monde est d'accord.
Ensuite, dire que "librairie" est faux repose surtout sur le fait que c'est une mauvaise traduction de "library".
Ou alors, peut-être est-ce le fait que dans une librairie, on n'y trouve que des romans de gare et la dernière bouse de BHL...
Bref, rien de comparable avec la qualité de ce que propose une bibliothèque !
C'était mon-explication-de-moi-que-j'ai-et-que-je-partage
[^] # Re: librairie ?
Posté par Dr BG (site web personnel) . Évalué à 4.
[^] # Re: librairie ?
Posté par BAud (site web personnel) . Évalué à 3.
http://wordreference.com/enfr/library <- aucune occurence de librairie par traduction vers le français
http://wordreference.com/fren/librairie <- aucune occurence de library par traduction vers l'anglais
http://wordreference.com/fren/biblioth%C3%A8que
àmha http://fr.wiktionary.org/wiki/library t'indique - à raison - le terme de faux-amis ;-)
[^] # Re: librairie ?
Posté par pyrollo (site web personnel) . Évalué à 5.
[^] # Re: librairie ?
Posté par BAud (site web personnel) . Évalué à 3.
[^] # Re: librairie ?
Posté par rewind (Mastodon) . Évalué à 7.
# monodoc
Posté par TImaniac (site web personnel) . Évalué à 3.
http://www.mono-project.com/Monodoc_Editing
# Wiki-libra?
Posté par Maclag . Évalué à 3.
Faire une sorte de Wikipedia pour les bibliothèques de fonctions?
Ce serait un peu la forge de la documentation pour un projet.
Ca attirera peut-être des contributeurs de docs (ou de traduction de docs, pourquoi pas?), ça permettrait certainement aussi, avec une bonne gestion, de chercher et identifier rapidement une bibliothèque utile pour les développeurs, et ainsi donner plus de visibilité à certains travaux qui le mériteraient.
Bon, vous mettrez mon nom sur la page d'accueil pour l'idée, pour la mise en œuvre, je vous laisse faire...
[^] # Re: Wiki-libra?
Posté par jm trivial (site web personnel) . Évalué à 1.
Si un tel logiciel existe, on peut tout à fait envisager ensuite de proposer un service de forge autour de l'outil pour favoriser ensuite la recherche à l'intérieur des projets.
Par contre, il est peu probable que les méthodes de deux projets différents aient la même signature, donc on ne pourrait pas mutualiser les descriptions. On pourrait par contre mutualiser les descriptions abstraites. Par exemple si deux méthodes calculent des diagrammes de Voronoï, on pourrait utiliser la même page pour décrire la méthode.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Parce que , et je le déplore, la grande majorité des développeurs du libre s'imaginent que le code source suffit et est amplement suffisant.
Parce que la majorité des développeurs du libre en ont rien à faire des gens qui ne veulent ou ne peuvent passer des heures à lire des lignes de code source pour récupérer une info sur une ou deux classes.
Parce que beaucoup de développeurs, même dans le libre, développent "à l'arrache", codent "à la volée" sans avoir écrt une analyse préalable ..... ou alors ne partagent pas cette analyse.
Je déplore cette attitude. Pour moi la documentation devrait être faite avant de coder.
[^] # Re: Wiki-libra?
Posté par jm trivial (site web personnel) . Évalué à 2.
Le mode collaboratif est évident pour répondre à la situation.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Regarde un peu la vitesse à laquelle tout bouge dans le LL ....
Il faut que la doc soit faite en même temps par les développeurs ou elle aura 3 versions de retard.
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 3.
Tout rejeter sur le dos des développeurs, c'est facile mais contre-productif. L'idée de faire de la documentation partagée me semble beaucoup plus efficace, et encourage, si tu ne trouve pas ce que tu cherches sur la doc partagée officielle, à l'ajouter quand tu le trouves ailleurs pour que tout le monde en profite. En plus ça peut permettre aux développeurs de voir ce qui manque (si quelqu'un poste un commentaire dans ce sens), et ce qui n'est pas clair pour tout le monde (si une partie est très documentée en général c'est que l'utilisation n'était pas intuitive ou le code mal documenté à la base).
Et puis, il faut se rendre à l'évidence, maintenant le développement et surtout le développement en LL ça se fait de plus en plus sur des bases collectives. C'est à dire que, même en solo, on a de plus en plus à utiliser des outils collaboratifs du genre github qui permettent de centraliser le code versionné, une wiki, la gestion de la collaboration d'autres développeurs, et la publicité des travaux. Que l'on y travailles activement en essayant de réaliser un outil spécialisé ou qu'on laisse l'auto-organisation faire son bonhomme de chemin. Après tout, avec un système à la github, n'importe qui peut trouver le projet, cloner le dépôt git, patcher pour ajouter de la doc sans rien casser et soumettre le patch au mainteneur qui n'a aucun effort à fournir ou presque pour l'intégrer, et il en va de même pour la wiki.
[^] # Re: Wiki-libra?
Posté par Epy . Évalué à 2.
Ça permet d'avoir le code et la doc en même temps, sans que les devs ne "s'ennuient" à rédiger la doc. Maintenant, il faut aussi prendre un peu de temps pour expliquer leur soft à des non devs sans que cela ne les "ennuie" non plus, mais ça doit quand même prendre nettement moins de temps (et être moins chi*nt) que rédiger des phrases bien faites.
Je suis un peu dans ce cas justement, j'ai eu des cours de dev pendant mon BTS mais je ne suis pas arrivé à intégrer les principes suffisament bien (et j'avais plus envie de développer non plus) ce qui me permet de comprendre pas mal de choses sans forcément savoir les faire. Et rédiger de la doc pour un soft qui me plaît m'intéresse ça me permettrai de participer au logiciel libre un peu plus.
(Tout cela sans abandonner l'excellente idée de la rédaction collaborative de la doc bien sûr, c'est un plus)
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 2.
On peut prendre l'exemple de ton BTS : si tu as travaillé en équipe avec des outils collaboratifs (on va dire avec git, puisque c'est à la fois le plus populaire en ce moment et le meilleur, j'assume le troll), dans ton équipe il y a sans doute des gens qui avaient plus d'affinité avec la rédaction et d'autres qui étaient plus à l'aise avec le code. Plutôt que de vouloir que tout le monde contribue de la même façon au code, il vaut mieux prendre un peu de temps avant et bien expliquer le B.A. BA de l'outil de versionnage, et lancer qui sur sa partie d'affinité (avec une personne dédiée à maîtriser la cohérence du dépôt central).
Même chose pour les projets libres, avec un bon outil (dois-je redire git ?) c'est facile de patcher et de mettre le patch à disposition du mainteneur. Après, chacun peut faire avec ses forces plutôt que d'être bloqué par ses faiblesses, du moment qu'un tout petit peu de savoir sur le système de contrôle de code est présent, dans la tête des contributeurs et dans un tutorial simple.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
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 ....
Tout rejeter sur le dos des développeurs, c'est facile mais contre-productif
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.
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.
L'idée de faire de la documentation partagée me semble beaucoup plus efficace, et encourage, si tu ne trouve pas ce que tu cherches sur la doc partagée officielle, à l'ajouter quand tu le trouves ailleurs pour que tout le monde en profite.
D'accord avec toi, cependant les développeurs doivent en faire un minimum. Et la il s'agit plus d'adopter des conventions et des normes communes dans un développement, qui pourront être utilisés par des outils tiers pour centraliser cette doc. Il faut aussi en cas de besoin avoir un chemin inverse : reporter les modifications de la doc "en ligne" par exemple vers le code source .... un peu ambitieux mais pourquoi pas ?
Juste une queston : as-tu déjà essayé de documenter un projet que tu ne connais pas, rien qu'à partir du code source ? Moi, oui, et le temps de documenter ce que tu as compris, c'est obsolète car une ou deux autres versions du projet sont sorties et tout est à refaire.
[^] # Re: Wiki-libra?
Posté par Bastes . É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.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Je pense que tu n'as pas compris mon commentaire :
On préfère acheter une bibliothèque payante, fermée mais bien documentée (pour l'utilisation) qu'une bibliothèque libre, code ouvert et peu documentée, parce qu'un développeur qui doit passer des jours à ausculter le code pour comprendre comment ça marche, ça coute cher ....
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.
On est pas obliger d'expliciter tous les cas possible. Cependant ce qui pour moi constitue un bon exemple de documentation bien faite (mais pas parfaite) c'est par exemple la documentation de VBA dans Excel.
Tu as une aide et une explication sur les fonctions, les paramètres qu'elles prennent ainsi qu'un exemple d'utilisation. Tu n'as pas un exemple sur tous les cas d'utilisation, mais suffisamment pour comprendre comment ça marche.
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
C'est vrai mais ce n'est pas la seule raison : voir plus haut.
Je vais prendre un autre exemple Ruby : Rails. La doc de base est extrêmement bien faite
Non.
Ruby on Rails est l'exemple typique de ce que je déplore : on sort une version (notamment la 2.0), et on ne sort pas de doc associée. Quelqu'un qui connait un peu ruby ou rails s'en sort mais je t'assure que quelqu'un qui a voulu se mettre à Ruby lorsque Ruby 2.0 est sorti aurait pu être totalement dégouté de ce langage. D'ailleurs, quand j'allais en cours, il y a plus de 10 ans, on m'a toujours encouragé à écrire un minimum de documentation _avant_ d'écrire mon code, d'écrire par exemple, pour une fonction, les paramètres qu'elle prend, le type et l'utilité de ces paramètres, ainsi que le code retour. On encourage également, dans certaines méthodes de développement, de décrire clairement les classes que l'on crée (notamment à l'aide d'UML), et ce _avant_ de commencer à coder. On encourage aussi à écrire les procédures de test unitaure _avant_ de coder les classes/fonctions (Methodes XP par exemple), et ce n'est pas pour rien.
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.
Ce n'est pas non plus ce que je leur demande .... mais on peut leur en demander un minimum .... Et pour moi le minimum c'est d'expliquer comment utiliser le code qu'ils ont produit et ce que fait ce code.
En fait j'aimerais avoir pour certains projets libre, non seulement le code mais surtout les représentations (UML) de l'ensemble du projet. Mais la on s'éloigne du sujet initial (les bibliothèques) ...
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 2.
> On préfère acheter une bibliothèque payante, fermée mais bien documentée (pour l'utilisation) qu'une bibliothèque libre, code ouvert et peu documentée, parce qu'un développeur qui doit passer des jours à ausculter le code pour comprendre comment ça marche, ça coute cher ....
Payer ne te donne pas de garantie que ce soit propre et clair, juste une personne à blâmer si ça ne l'est pas et l'impression d'avoir un levier. Tu peux avoir du propre et du clair aussi bien en libre qu'en non-libre et le crade et pas clair n'est pas l'apanage du libre non plus.
Et j'ai très bien compris ton commentaire, mais je ne suis pas d'accord.
> Non.
> Ruby on Rails est l'exemple typique de ce que je déplore : on sort une version (notamment la 2.0), et on ne sort pas de doc associée. Quelqu'un qui connait un peu ruby ou rails s'en sort mais je t'assure que quelqu'un qui a voulu se mettre à Ruby lorsque Ruby 2.0 est sorti aurait pu être totalement dégouté de ce langage. D'ailleurs, quand j'allais en cours, il y a plus de 10 ans, on m'a toujours encouragé à écrire un minimum de documentation _avant_ d'écrire mon code, d'écrire par exemple, pour une fonction, les paramètres qu'elle prend, le type et l'utilité de ces paramètres, ainsi que le code retour. On encourage également, dans certaines méthodes de développement, de décrire clairement les classes que l'on crée (notamment à l'aide d'UML), et ce _avant_ de commencer à coder. On encourage aussi à écrire les procédures de test unitaure _avant_ de coder les classes/fonctions (Methodes XP par exemple), et ce n'est pas pour rien.
Mais tu compares des choses non comparables, les n° de version ne veulent pas dire la même chose en libre et en privateur.
Dans le cas de Ruby ou de Rails, par exemple, les numéros de version se lisent :
x.y.z où x représente un très gros changement fondemental de l'API, y un apport de nouvelles fonctionalités majeurs ou des changements importants mais pas critiques, et x des changements mineurs ou des bugkills. Rien ne te garantis que la version 2.0.0 soit plus stable qu'une version 1.8.7 ou 0.1.23, je dirais même que la version 2.0.0 a beaucoup plus de chances d'être bugée, sa documentation incomplète ou à revoir par endroits. Dans ce cas, il vaut mieux rester une version en arrière de la pointe si tu veux de la stabilité et de la doc lisse.
Dans le cas d'un modèle privateur, puisque c'est un produit que l'on vend, on ne sort une nouvelle version qu'une fois que tout est lisse, arrondi, calé, ou du moins que les bugs sont cachés sous le tapis, et on lui met un gros numéro bien flamboyant pour dire "tadaaaaaa". Ici ça ne sert à rien d'être une version en dessous de la pointe, puisque la pointe n'est pas disponible avant d'être stabilisée.
Enfin, si tu veux de la méthodologie XP avec tests validés avant commit tu peux difficilement accuser Rails de ne pas être à la pointe de cette pratique. Pour écrire les tests avant codage, je ne suis pas dans le secret de l'équipe Rails core, mais moi-même en toute honnêteté je ne le fais pas toujours, et il m'arrive de me demander si c'est vraiment si meilleur que de les faire peu de temps après avoir fait une fonctionnalité (mais avant de factoriser bien entendu).
> Ce n'est pas non plus ce que je leur demande .... mais on peut leur en demander un minimum .... Et pour moi le minimum c'est d'expliquer comment utiliser le code qu'ils ont produit et ce que fait ce code.
En général les fichiers README sont là pour ça, et le commentaire aussi, en tout cas en Ruby (je n'ai pas fait beaucoup de C, VB, ou autres langages "chiants" en dehors du Java et du PHP...). Après il y a des gens qui ne lisent pas les readme ou les commentaires (en Ruby on génèrent les docs facilement à partir des commentaires, et comme contrairement à Java on ne fait pas plein de méthodes creuses qui appellent en fait une autre méthode qui fait vraiment le boulot, c'est moins fatiguant).
> En fait j'aimerais avoir pour certains projets libre, non seulement le code mais surtout les représentations (UML) de l'ensemble du projet. Mais la on s'éloigne du sujet initial (les bibliothèques) ...
Il n'y a pas que l'UML dans la vie...
Tu parlais d'XP, en XP on travaille beaucoup plus à partir de "stories", on fait des schémas beaucoup plus libres et peut tout à fait les inclure là où ils vont, c'est à dire dans une wiki de projet par exemple.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Payer ne te donne pas de garantie que ce soit propre et clair, juste une personne à blâmer si ça ne l'est pas et l'impression d'avoir un levier. Tu peux avoir du propre et du clair aussi bien en libre qu'en non-libre et le crade et pas clair n'est pas l'apanage du libre non plus.
Là n'est pas la question : tu sépares la doc du code et cette approche est bien plus rapide que de tout mettre dans le code. Après si quelqu'un veut vendre ses bibliothèques, il a intéret à bien écrire sa doc .... Après je t'accorde que payer n'est pas en soi une garantie d'avoir une documentation de qualité, mais souvent ça aide (tout dépend aussi à qui tu t'adresses, mais c'est un autre pb).
Et j'ai très bien compris ton commentaire, mais je ne suis pas d'accord. La réponse que tu as apporté ne le laissait pas paraitre ....
Mais tu compares des choses non comparables, les n° de version ne veulent pas dire la même chose en libre et en privateur
Dans le cas de Ruby ou de Rails, par exemple, les numéros de version se lisent :
x.y.z où x représente un très gros changement fondemental de l'API, y un apport de nouvelles fonctionalités majeurs ou des changements importants mais pas critiques, et x des changements mineurs ou des bugkills. Rien ne te garantis que la version 2.0.0 soit plus stable qu'une version 1.8.7 ou 0.1.23, je dirais même que la version 2.0.0 a beaucoup plus de chances d'être bugée, sa documentation incomplète ou à revoir par endroits. Dans ce cas, il vaut mieux rester une version en arrière de la pointe si tu veux de la stabilité et de la doc lisse.
Je suis d'accord avec toi sur le fait qu'une version non stable n'a pas à être documenté, je parle de version stable. Et lorsque j'ai installé Rails 2, c'était une version considérée comme stable ( ou j'ai mal compris quelque chose).
Dans ce cas, il vaut mieux rester une version en arrière de la pointe si tu veux de la stabilité et de la doc lisse.
C'est ce que j'ai fait .... et ça s'est plutot bien passé (je ne reviendrai plus au PHP).
Dans le cas d'un modèle privateur, puisque c'est un produit que l'on vend, on ne sort une nouvelle version qu'une fois que tout est lisse, arrondi, calé, ou du moins que les bugs sont cachés sous le tapis, et on lui met un gros numéro bien flamboyant pour dire "tadaaaaaa". Ici ça ne sert à rien d'être une version en dessous de la pointe, puisque la pointe n'est pas disponible avant d'être stabilisée.
Tu caricatures ..... Je ne suis pas spécialiste Microsoft, ou Borland, mais je me rappelle que lorsque je faisais du développement Windows, l'API était sufisamment bien documentée pour pouvoir s'en sortir dans la plupart des cas .... Toi tu me parles de développements fait à l'arrache par une sSII pour un projet spécifique, et la je te l'accorde les SSII ne sont pas toujours des modèles dans le genre.
En général les fichiers README sont là pour ça, et le commentaire aussi, en tout cas en Ruby (je n'ai pas fait beaucoup de C, VB, ou autres langages "chiants" en dehors du Java et du PHP...).
On en revient à ce que je disais plus haut : lire les commentaires parsemés dans le code, ca coute cer en temps à un développeur, bien plus qu'une aide en ligne à la "VBA" .... Apres entre le README qui indique comment installer, le README qui indique comment l'utiliser, etc .... c'est pas simple de s'uy retrouver.
Après il y a des gens qui ne lisent pas les readme ou les commentaires (en Ruby on génèrent les docs facilement à partir des commentaires, et comme contrairement à Java on ne fait pas plein de méthodes creuses qui appellent en fait une autre méthode qui fait vraiment le boulot, c'est moins fatiguant).
Je n'ai pas encore assez de recul sur Ruby et Rails pour répondre, mais ce n'est malhereusement le cas que d'une infime partie des projets libres. Pour beaucoup, la seule doc est le code ..... Et puis pour Ruby et rails en particulier il est difficile de s'y mettre sans un bon bouquin à côté ....
Enfin, si tu veux de la méthodologie XP avec tests validés avant commit tu peux difficilement accuser Rails de ne pas être à la pointe de cette pratique. Pour écrire les tests avant codage, je ne suis pas dans le secret de l'équipe Rails core, mais moi-même en toute honnêteté je ne le fais pas toujours, et il m'arrive de me demander si c'est vraiment si meilleur que de les faire peu de temps après avoir fait une fonctionnalité (mais avant de factoriser bien entendu).
Dans un contexte de travail collaboratif, c'est mieux : tu définis les interfaces avant de les implémenter :ceux qui se basent sur ton travail peuvent travailler sans avoir à t'attendre .... Et tu remarqueras que pour ma part je ne parlais pas de Rails mais que j'étais dans une optique plus globale.
Il n'y a pas que l'UML dans la vie...
Tu parlais d'XP, en XP on travaille beaucoup plus à partir de "stories", on fait des schémas beaucoup plus libres C'était un exemple ..... ne prends pas mes propos au pied de la lettre. Que ce soit UML ou autre chose, ce n'est pas le plus important. JE parle d'UML parce que ç'est un ensemble d'outils normalisés et qui restent assez clair et "universel". Cela dit si chacun utilise sa propre convension, comment veux-tu ensuite regrouper tout ça dans un ensemble cohérent (ce qui était l'objet du fil initial) ...
et peut tout à fait les inclure là où ils vont, c'est à dire dans une wiki de projet par exemple.
1/ D'abord combien de projets le font ? très peu. Et c'est ce que je déplore entre autres.
2/ Sinon, encore de la dispersion :
- Readme
- code source
- wiki projet
- les forums
- les FAQ
- un bouquin qui fait la glue avec ça ...
Et tout ca sans que les développeurs s'impliquent dans la doc (je ne leur demande pas de rédiger de la doc hein) ... En plus chaque projet ou langage utilise ses propres convensions ou format ..... Pour un développeur windows par exemple c'est plus simple : un IDE qui contient l'aide dont il a besoin ....
Si on pouvait arriver à ca je serais hereux .... mais j'y crois pas trop.
3/ Qu'est-ce qui empêche de rédiger de la doc en même temps que les tests ? Pas grand chose puisque les tests sont censé, comme leur nom l'indique, testerles cas d'utilisation. Prendre certains bouts de code développés pour le test comme exemple serait bien pratique ....
Juste un détail : ne prends pas mes commentaires comme si je crachais sur le LL et les développeurs : j'essaie d'être constructif et de mettre en avant les points qui me paraissent négatifs dans le LL, et je serai le premier hereux lorsque ces problèmes auront disparu.
En fait de cette discussion me viennent des idées, mais je ne pense pas que les développeurs s'y plieraient ... Ya qu'a voir les tentatives d'uniformisations telles que LSB ou autres pour se faire une idée ....
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Je m'exprime mal : disons que je ne leur demande pas d'écrire un roman .....
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 3.
On ne doit pas parler de la même chose alors. A volume égal, la doc des méthodes et des objets eux-mêmes, plus tu la détache et plus c'est pénible de la garder à jour, alors que la mettre proprement dans les commentaires prévus à cet effet permet de générer sous différents formats de façon automatisée sans perdre du temps à synchroniser à la main.
Par contre, si à fonctionnalité égale je dois commenter une seule méthode (Ruby) ou 3 méthodes (Java quand il y a plusieurs façons de fournir les paramètres), c'est clair je préfère Ruby.
> Je suis d'accord avec toi sur le fait qu'une version non stable n'a pas à être documenté, je parle de version stable. Et lorsque j'ai installé Rails 2, c'était une version considérée comme stable ( ou j'ai mal compris quelque chose).
Alors non on n'est pas d'accord. Je ne vois pas en quoi on ne devrait pas documenter une version non stable. Mais je crois que tu veux dire en fait "une version non stable n'a pas à sortir publiquement". Et là, vu que tu adopte un point de vue privateur, oui, c'est logique.
Dans un modèle de développement libre, on peut très bien rendre publiquement disponible même (surtout) les version non stables, en avertissant les visiteurs que la version non stable ne l'est pas encore. C'est comme ça que des utilisateurs peuvent soumettre des patchs pour stabiliser, indiquer les bugs qu'ils trouvent, et aider à évaluer la stabilité de l'ensemble. Aussi, à soumettre des patchs de commentaires pour améliorer la documentation.
Et que tu aies compris quand tu as installé Rails 2.0.0 que c'était une version stable... Comment te dire... Tu as mal compris quelque chose, oui.
>> Dans le cas d'un modèle privateur, puisque c'est un produit que l'on vend, on ne sort une nouvelle version qu'une fois que tout est lisse, arrondi, calé, ou du moins que les bugs sont cachés sous le tapis, et on lui met un gros numéro bien flamboyant pour dire "tadaaaaaa". Ici ça ne sert à rien d'être une version en dessous de la pointe, puisque la pointe n'est pas disponible avant d'être stabilisée.
> Tu caricatures ..... Je ne suis pas spécialiste Microsoft, ou Borland, mais je me rappelle que lorsque je faisais du développement Windows, l'API était sufisamment bien documentée pour pouvoir s'en sortir dans la plupart des cas .... Toi tu me parles de développements fait à l'arrache par une sSII pour un projet spécifique, et la je te l'accorde les SSII ne sont pas toujours des modèles dans le genre.
Non, je ne caricature pas, je constate. De plus je ne juge pas. C'est normal d'essayer de faire mousser un produit que l'on veut vendre, et c'est normal qu'on lisse les bords et qu'on arrondisse les coins, voir qu'on mette de la poussière sous le tapis quand il y en a qu'on n'a pas le temps de vider, tout le monde le fait, ce n'est pas l'apanage des SSII et Windows ou Borland ne sont pas en reste. De toute façon ce n'est pas un crime et ça peut être réparé discrètement ensuite à coups de patchs.
Et surtout, ce n'est pas une décision volontaire d'un dirigeant ou des développeurs, c'est un sous-produit du modèle en cascade "on livre pour quand c'est demandé / quand le marché est réceptif" comme le fait de soumettre des versions non stable est un sous-produit du modèle itératif "on livre petit à petit jusqu'à ce que ça fonctionne bien et quand ça fonctionne bien on appelle ça stable jusqu'à la prochaine stable".
> On en revient à ce que je disais plus haut : lire les commentaires parsemés dans le code, ca coute cer en temps à un développeur, bien plus qu'une aide en ligne à la "VBA" .... Apres entre le README qui indique comment installer, le README qui indique comment l'utiliser, etc .... c'est pas simple de s'uy retrouver.
Sinon tu as des outils pour prendre les commentaires et faire les jolies pages HTML lisibles / cherchables avec le code caché tant que tu ne veux pas le voir, avec Ruby ça s'appelle RDoc, avec Java JavaDoc, avec PHP, PHPDoc (c'est dingue, on dirait presque qu'ils se sont concertés). Ils peuvent par exemple prendre le README et en faire une jolie page de garde avec des titres et tout.
Avec ça, tu rajoutes un wiki sur ton site, où tu mets des schémas globaux, des explications sur les principes importants, des tutoriaux pour les tâches courantes, et n'importe qui peut s'y retrouver. Le point positif, c'est que c'est moins lourd et chiant à maintenir qu'une documentation complètement séparée du code, parce que quand on change la signature d'une méthode qui a un commentaire, on pense plus facilement à changer le commentaire et c'est moins pénible que de repasser sur toute la doc et tout le code pour voir les choses qui ont changé après coup.
> Je n'ai pas encore assez de recul sur Ruby et Rails pour répondre, mais ce n'est malhereusement le cas que d'une infime partie des projets libres. Pour beaucoup, la seule doc est le code ..... Et puis pour Ruby et rails en particulier il est difficile de s'y mettre sans un bon bouquin à côté ....
A mon avis oui, tu as assez peu de recul sur Ruby on Rails, probablement parce que tu as attaqué Rails sans avoir au préalable un peu creusé Ruby. C'est ce qui fait que oui, il faut généralement un bouquin pour attaquer parce que sinon c'est un trop grand pas à franchir.
C'est un peu comme vouloir apprendre le calcul intégral sans savoir faire d'additions, soustractions, multiplications, etc., c'est pas strictement impossible mais il va falloir beaucoup potasser et tu vas trouver ça beaucoup plus compliqué.
Ensuite, je pense que si je voulais attaquer le développement d'un jeu en 3D avec directX en C++, j'aurais quand même intérêt d'avoir des bases de C++ avant d'attaquer l'API directX par la face nord, API bien foutue ou pas.
Et puis franchement, commencer dans n'importe quelle API en plongeant direct dans l'API sans chercher des autres sources (tutos, blogs, forums de développeurs, etc.) c'est quand même un peu suicidaire non, à moins de déjà maîtriser à mort le sujet.
> Dans un contexte de travail collaboratif, c'est mieux : tu définis les interfaces avant de les implémenter :ceux qui se basent sur ton travail peuvent travailler sans avoir à t'attendre ....
En Java oui, puisque le Java est fortement typé, que d'écrire du code prends beaucoup de temps, qu'il y a beaucoup de répétitions inutiles (méthodes paravent, polymorphisme par clonage de signatures, répartition de responsabilités en multipliant le nombre de classes ...), ce qui oblige à faire des architectures de classes apriori pour faire en sorte que tout colle bien ensuite, ce qui plombe les projets parce que tout ne se passe jamais vraiment comme c'était prévu au départ (le client change d'avis, l'équipe avait mal compris / interprété, une contrainte technique force à considérer un cas imprévu...). C'est bureaucratique, lourd, et généralement ça tue l'esprit d'initiative chez les gens qui vont devoir développer derrière les architectes qui on fait les plans. Bof.
Maintenant, quand le langage n'est pas une carapace handicapante, comme en Ruby (typage dynamique "... alors pour moi c'est un canard", possibilité d'ajouter des comportements factorisés dans la définition de classe ou même à la volée grâce aux modules, etc.), on n'a pas besoin de tout penser avant de se mettre à coder, on peut commencer en itératif en définissant des lignes générales, prototyper jusqu'à obtenir un modèle convenable, casser le prototype et réaliser l'itération avec tests et factoriser ensuite. Et la collaboration se passe bien s'il y a communication, proximité, tests automatisés et confiance, ces 4 éléments sont nécessaires et c'est non-négociables par contre.
Il faut faire confiance apriori en sa capacité à trouver une solution pour chaque problèmes qui se présenteront en route, mais que l'on parte avec un plan rigide et sur-développé comme en Java ou une direction globale précise mais une ligne souple comme en Ruby, on arrive au même point au final et il y aura des embûches en cours de route de toute façon (le meilleur plan du monde n'est qu'un plan, la réalité a souvent tendance à le contredire).
et peut tout à fait les inclure là où ils vont, c'est à dire dans une wiki de projet par exemple.
> 1/ D'abord combien de projets le font ? très peu. Et c'est ce que je déplore entre autres.
Plein de projets libres le font, au contraire, mais ils ne sont pas forcément toujours très connus / reconnus par les utilisateurs. Github par exemple propose de base un wiki pour chaque projet.
Au hasard dans ceux que j'utilise et que je lis beaucoup :
- Rails (beaucoup de tutos sont justement sur la Wiki)
- Shoes (toolkit graphique Ruby)
- Inkscape
- Ubuntu
> 2/ Sinon, encore de la dispersion :
> - Readme
> - code source
> - wiki projet
> - les forums
> - les FAQ
> - un bouquin qui fait la glue avec ça ...
Attends, tu mélanges tout là.
Le README ça va avec le code source, et ça peut être inclu dans la doc généré, généralement d'ailleurs ça fait la première page de doc générée automatiquement depuis les sources.
Un wiki projet c'est pour trouver les bases pour commencer, ça n'a rien à voir avec les sources et c'est normal, le but n'est pas d'aller au fond des choses mais de présenter une vue d'ensemble et des "portes d'entrées" dans les concepts principaux. C'est normal que ça ne soit pas intégré à la doc de l'API plus complète, moins didactique, plus directe, plus "sèche" (moins d'exemples pas à pas). Les FAQ ça s'intègre très bien aux wiki, c'est même limite la meilleur façon de les case.
Les forums officiels c'est là pour mettre en relation une question précise avec une réponse précise, quand une question - réponse revient souvent c'est une bonne idée de la faire remonter vers la wiki, ou dans la doc quand c'est un trou. C'est un autre média, ça n'a rien à voir, et rien n'empêche de le mettre sur un même nom de domaine que le site de l'API et du code par exemple.
Les forums officieux, les bouquins, c'est pas maîtrisable par les responsables du projet, chacun fait ce qu'il veut et encore heureux.
Bref, de tous ces différents médias, les "officiels" sont tous groupables sous un même nom de domaine commun, et les "officieux" font leur vie. En même temps c'est plutôt bien de disperser les médias officieux, ça diffuse l'information, ça donne des droits d'auteur à des auteurs de livres, quand ils sont bons, ça fait bloguer les blogueurs.
> Et tout ca sans que les développeurs s'impliquent dans la doc (je ne leur demande pas de rédiger de la doc hein) ... En plus chaque projet ou langage utilise ses propres convensions ou format ..... Pour un développeur windows par exemple c'est plus simple : un IDE qui contient l'aide dont il a besoin ....
> Si on pouvait arriver à ca je serais hereux .... mais j'y crois pas trop.
Ok, je ne sais pas toi, mais moi la dernière fois que j'ai consulté la MSDN je m'y suis perdu et je n'ai pas trouvé la réponse après une soirée, j'ai laissé tomber. Comme quoi c'est aussi subjectif, et qu'un outil demande un temps de prise en main de toute façon et quel qu'il soit.
> 3/ Qu'est-ce qui empêche de rédiger de la doc en même temps que les tests ? Pas grand chose puisque les tests sont censé, comme leur nom l'indique, testerles cas d'utilisation. Prendre certains bouts de code développés pour le test comme exemple serait bien pratique ....
Rien ne l'empêche, mais c'est pas forcément une bonne idée, tout comme celle qui voudrait que les tests sont fait au début et n'évoluent pas ensuite. On ne sait pas de quoi demain sera fait, il vaut mieux écrire les tests et les commentaires peu de temps avant le code, et les faire évoluer quand le code évolue pour mieux convenir aux besoins.
Considérer la programmation d'une façon verticale (on descend d'une vérité mathématique absolue jusqu'à lui donner corps) me semble être une erreur. Je préfère l'approche "biologique", on prend un problème, on le résout, on consolide, on livre, on prend de l'expérience, on réitère. C'est plus "darwinien" (le meilleurs finit pas survivre et transmet ses caractéristiques aux suivants), et moins "immanent" (la perfection existe au-delà de notre royaume, mais on doit s'en approcher quel que soit le prix).
> Juste un détail : ne prends pas mes commentaires comme si je crachais sur le LL et les développeurs : j'essaie d'être constructif et de mettre en avant les points qui me paraissent négatifs dans le LL, et je serai le premier hereux lorsque ces problèmes auront disparu.
Je ne le prend pas comme une insulte, mais plutôt comme un point de vue biaisé concernant le mode de fonctionnement de projets libres. C'est pourquoi je défend mon point de vue jusqu'à changement de celui-ci et / ou fin de la discussion.
Je ne suis pas un zélote d'un fonctionnement ou l'autre (même si je préfère moi me trouver dans un mode de fonctionnement itératif, c'est un choix personnel, que je défend mais que je n'impose pas), chacun peut mieux convenir selon la situation. Par contre, appliquer un modèle ou l'autre a des conséquences sur le format de la documentation officielle et de l'information en général, et attaquer l'api d'un projet libre avec les apriori d'un projet privateur n'a pas de sens, et ne peut que te mener à l'échec et à la frustration, l'inverse est vrai aussi.
> En fait de cette discussion me viennent des idées, mais je ne pense pas que les développeurs s'y plieraient ... Ya qu'a voir les tentatives d'uniformisations telles que LSB ou autres pour se faire une idée ....
Justement, pourquoi faire uniforme ? Est-ce que le monde sera plus beau et plus vivable quand on vivra dans des petites cases de béton de taille réglementaire, avec le choix de la couleur intérieure parmis les couleurs réglementaires, avec les meubles et la décoration à choisir dans les meubles et les décorations standards ?...
Le libre c'est la liberté d'expérimenter comme on le sent, c'est valable aussi pour la documentation. C'est un modèle vivant, presque organique, qui peut donner des bases stables (après tout, l'évolution naturelle a bien donné à l'essentiel des espèces vivantes une même base standard, l'ADN, il n'y a pas de raison que la liberté de création en informatique ne puisse pas reposer sur des standards quand ils sont plus adaptés) mais pas indépassables le jour où on trouve une meilleur idée. Vouloir mettre tout dans des cases bien propres c'est le mirage un peu schizo d'un Descartes qui pensait les animaux comme des machines biologiques déterminées en même temps que "Je pense donc je suis". La vie ne rentre pas dans des petites cases, ou alors avec un truc coupant bien aiguisé...
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Bien si on veut pouvoir centrer de la documentation par exemple, il faut pouvoir se mettre d'accord sur un certain nombre de choses ... L'idée qui me vient à l'esprit serait de pouvoir générer de la doc pour un IDE par exemple, à partir de la documentation contenue dans les commentaires d'un code source. Je ne sais pas si ça existe mais peu importe, ce n'est qu'un exemple. Pour que ça marche ce truc il faudrait que les développeurs suivent une certaine norme ou ce projet est voué à l'échec.
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 2.
Quand je parlais de documentation qui ne rentre pas dans des petites cases carrées, je voulais par exemple parler de celle de shoes, qui incite à se remettre la tête ronde quand elle commence à devenir trop bêtement carrée :
http://shoooes.net/
Après, il y a des gens à qui ça fait peur, moi j'aime bien.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Ah, j'oubliais de préciser : dans le monde de l'entreprise on a besoin de standards ....
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Non, je raisonne en terme de doc à jour et utilisable par quelqu'un qui ne connait pas forcément le projet, par rapport à la version livrée.
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 2.
Si tu veux comparer ce qui est comparable, commence par prendre une version stable (pas Rails 2.0.0 mais plutôt 2.2.2 par exemple) et ne prends pas la version "edge" puisque que c'est celle qui est encore en travaux, donc où la doc est la moins à jour et les bugs imprévus pas encore réparés.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Non, je raisonne en document _utilisable_ point barre. pour une version stable d'une bibliothèque ou d'un projet. En quoi le fait d'être libre/proptrio/contrat ou n'importe quoi change-t-il quelque chose ? On s'en fout, ce que je veux c'est pouvoir utiliser la doc sans me prendre trop la tête.
Ce n'est pas le modèle de rails par exemple. Comparer les documentations générées par ces deux formes de développement sur le critère de la validité de la doc d'une seule version V à un moment arbitraire, c'est privilégier le premier modèle où il n'y a pas beaucoup de V, alors que dans le second modèle on fait en continu des versions V, V', V'', etc. sans forcément que la dernière soit la plus stable ou la mieux documentée.
Et qu'est-ce qui empêche d'avoir une doc à jour par rapport aux évolutions de version ? Le temps que ca prend? Ca n'a pas de sens : soit tu documentes et on utilise ton code, quitte à prendre plus de temps, sit tu documentes pas et personne n'utilise ton code et la ça sert à rien d'aller vite. De plus en mettant la doc à jour au fur et à mesure ça prend moins de temps plutot que de générer une doc après que la version soit sortie (et cette doc ne sera jamais à jour car le temps d'écrire la doc, la version N+1 sort)..... Et je te répète que je ne cherche pas une doc à jour pour la derniere version non stable, mais pour une version stable.
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 2.
Il y a plein d'utilisateurs de Rails qui trouvent la doc de l'api très utilisable et pas prise de tête, moi en tête. Je m'en sers tous les jours, j'y trouve ce que je cherche rapidement et je trouve que c'est généralement assez clair et complet.
Sinon, ce que ça change d'être libre ou privateur, beaucoup de chose, j'ai développé dans un autre message plus haut. La question "comment faire pour obtenir des projets libres qu'ils soient des copies conformes mais gratuites des privateurs" est un non-sens. La bonne question est "est-ce que ce que j'attends est un projet libre, qui avance au fur et à mesure, qui évolue et change, ou est-ce que je veux travailler sur le marbre d'un produit privateur complètement fini avec une documentation parfaitement stable". Apparemment tes désirs te feront préférer la 2° catégorie. Si tu demandes à un léopard de porter des rayures, ou un zèbre de porter des taches, tu seras souvent déçu par la réalité....
> Et qu'est-ce qui empêche d'avoir une doc à jour par rapport aux évolutions de version ? Le temps que ca prend? Ca n'a pas de sens : soit tu documentes et on utilise ton code, quitte à prendre plus de temps, sit tu documentes pas et personne n'utilise ton code et la ça sert à rien d'aller vite. De plus en mettant la doc à jour au fur et à mesure ça prend moins de temps plutot que de générer une doc après que la version soit sortie (et cette doc ne sera jamais à jour car le temps d'écrire la doc, la version N+1 sort)..... Et je te répète que je ne cherche pas une doc à jour pour la derniere version non stable, mais pour une version stable.
L'API, rien n'empêche qu'elle soit à jour, et au risque de te surprendre à de rares exceptions près elle l'est. Par contre, les blogs de trucs et astuce et certaines pages de la wiki officielle ne sont pas toujours maintenues comme elles devraient. D'où une interrogation : en parlant de l'API, ne parlerais-tu pas en réalité de la wiki de Rails ? (l'api : http://api.rubyonrails.org/, la wiki : http://wiki.rubyonrails.org/)
L'API donc est générée à partir des commentaires du code, automatiquement, elle est donc généralement très à jour (sauf peut-être quelques jours de temps en temps quand une nouvelle version importante remplace la précédente edge, et encore) tout comme les commentaires du code donc. Celle du site concerne la dernière version edge, mais comme c'est celle générée automatiquement si tu n'utilise pas la dernière edge tu peux très bien générer la documentation de ta version à partir de ta version avec un " rake doc:rails ", ça te génère un répertoire avec une version HTML complète et navigable des commentaires correspondant à ta version en cours à toi au temps t sur ta machine m.
En fait, j'ai vraiment l'impression à te lire que tu as foncé dans le Rails tête baissée et que du coup tu es frustré parce que tu ne sais pas où trouver l'information et savoir par où commencer. C'est valable pour d'autres projets que Rails, privateurs ou libres. Si tu avais commencé par exemple par demander de l'aide sur un forum pour savoir par où commencer, et cherché de l'information de base (sur internet, dans un livre synthétique, etc.), à mon avis tu serais maintenant plus à l'aise et tu n'aurait peut-être pas un avis aussi orienté sur la question.
Rappelles-toi tes premiers pas dans les projets informatiques, rappelles-toi quand on t'a tenu la main pour prendre en main tel ou tel outil que maintenant tu aimes employer, rappelles-toi les heures à chercher une information sans la trouver parce que tu ne savais pas où chercher.
Bien sûr on voudrait que le savoir et l'expérience nous tombent tout cuit tout roti, mais le monde n'est pas comme ça, ce n'est pas plus la faute aux projets libres ou privateurs, il faut chercher pour trouver de l'info, et pour trouver il faut savoir parfois dans quelle botte de foin se cache l'aiguille.
De ce point de vue la l'avantage du libre c'est de pouvoir faire appel à l'aide de la communauté, et de laisser libre accès en lecture / écriture à ceux qui veulent améliorer la documentation. Le privateur a d'autres avantages (ne proposer de la documentation que pour ce qu'il veut bien te laisser voir par exemple, ça peut être un atout pour ne pas s'épuiser à commenter tout, c'est juste un exemple). A toi de faire ton choix en fonction de tes besoins.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Je pense que si ce n'est déjà fait, on le pourra bientot ...
La question "comment faire pour obtenir des projets libres qu'ils soient des copies conformes mais gratuites des privateurs" est un non-sens.
Ce n'est pas ce que je demande. Seulement ici certains (dont toi) s'imaginent que rien n'est bon dans les logiciels proprio, et que tout ce qui est fait dans le libre est nécessairement bien, qu'il ne faut pas changer. Je ne suis pas comme toi, je considère que beaucoup de choses peuvent être améliorées dans le libre et que les idées du propriétaire ne sontpas forcément mauvaises.
La bonne question est "est-ce que ce que j'attends est un projet libre, qui avance au fur et à mesure, qui évolue et change, ou est-ce que je veux travailler sur le marbre d'un produit privateur complètement fini avec une documentation parfaitement stable"
N'import quoi, tu fais expres de ne pas comprendre ou quoi ? C'est quoi cette façon de déformer et reformuler ce que j'attends du libre ou de n'importe quoi d'autre ? D'ailleurs ce n'estpas moi qui en attend quelque chose. Je ne fais qu'exprimer un besoin que l'on rencontre dans le monde professionnel : une certaine stabilité et une documentation à jour par rapport aux versionss de logiciels/bibliothèques développées, sans avoir à aller fouiller dans du code pour trouver l'information dont on a besoin .... Est-ce siu dur que ça ?
Mettons un peu l'exemple Rails de côté, car je pense que ce n'est pas le pire, bien qu'il ne soit pas parfait, et je suis prêt à mettre mon expérience sur le fait que je me sois intéressé à Rails au mauvais moment ( les informations que j'ai pu trouver sur la version précédent la V2 de rails étaient, elles, assez pertinentes), et prenons en un autre : les pages man (ou info) de certains (voire beaucoup) de commandes par exemple. Nombre d'entre elles ne sont pas à jour (je te le dis tout de suite, je n'ai pas de liste précise, ceci est simplement une constatation que j'ai pu faire - il y a quelques années - lorsque j'utilisais Linux de façon plus intensive. Ceci a pu changer et je l'espère).
<i<L'API donc est générée à partir des commentaires du code, automatiquement, elle est donc généralement très à jour (sauf peut-être quelques jours de temps en temps quand une nouvelle version importante remplace la précédente edge, et encore)
Je suppose donc comme dit plus haut que c'est probablement ce qui a du se passer lorsque je me suis mis à Rails .....
n fait, j'ai vraiment l'impression à te lire que tu as foncé dans le Rails tête baissée et que du coup tu es frustré parce que tu ne sais pas où trouver l'information et savoir par où commencer.
Rappelles-toi tes premiers pas dans les projets informatiques, rappelles-toi quand on t'a tenu la main pour prendre en main tel ou tel outil que maintenant tu aimes employer, rappelles-toi les heures à chercher une information sans la trouver parce que tu ne savais pas où chercher.
Je suis autodidacte, je me suis mis à Linux sans qu'on me prenne par la main ....
Par contre je me suis mis à la programmation de l'API Windows en passant 1/2 journée avec quelqu'un qui avait développé un projet que je devais débugger. A l'époque c'était en Turbo PAscal me semble-t-il, jamais vu de ma vie (mais j'avais fait du C). Cependant la doc de l'IDE était tellement bien faite que je n'ai pas eu à me prendre la tête pour m'y mettre ....
Bien sûr on voudrait que le savoir et l'expérience nous tombent tout cuit tout roti, mais le monde n'est pas comme ça, ce n'est pas plus la faute aux projets libres ou privateurs, il faut chercher pour trouver de l'info, et pour trouver il faut savoir parfois dans quelle botte de foin se cache l'aiguille.
OK pour chercher des infos mais :
1 Si c'est à chaque pas que tu es obligé de tout retourner pour savoir ou aller il y a un problème
2 Ramené au monde de l'entreprise, ce n'est pas jouable. Et si les mentalités dans le libre ne changent pas, je crois qu'on verra jamais le libre percer significativement dans ce domaine.
De ce point de vue la l'avantage du libre c'est de pouvoir faire appel à l'aide de la communauté, et de laisser libre accès en lecture / écriture à ceux qui veulent améliorer la documentation. Le privateur a d'autres avantages (ne proposer de la documentation que pour ce qu'il veut bien te laisser voir par exemple, ça peut être un atout pour ne pas s'épuiser à commenter tout, c'est juste un exemple). A toi de faire ton choix en fonction de tes besoins.
Et dire que certains ici qualifient Stallmann d'extrémiste, mais ici j'en ai un bon exemple .... Pourquoi ne pas concilier les deux approches ? Je suis sur que c'est possible .... Encore faut-il le vouloir.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
[^] # Re: Wiki-libra?
Posté par Bastes . Évalué à 2.
Ah oui, quand il n'est pas libre, pas itératif et pas vivant.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 2.
Le fait d'être en constant développement n'empêche pas de se fixer des paliers stables avec une doc à jour. Si c'est ce que tu me raccontes l'"esprit du libre", je comprend pourquoi ça ne erce pas en entreprise et qu'on considère les LL comme des logiciels développés par des boutonneux sur un coin de table au lieu d'aller dans les soirées universitaires ....
[^] # Re: Wiki-libra?
Posté par Snarky . Évalué à 2.
Malheureusement, j'ai pas beaucoup de temps pour attaquer le gros du travail. Il faut juste que je fasse la base. Mais merci beaucoup de réanimer cette idée, car ça me motive de voir que beaucoup de gens attendent un tel projet.
[^] # Re: Wiki-libra?
Posté par totof2000 . Évalué à 4.
# En cogitation chez GNOME et GTK+
Posté par grafit . Évalué à 1.
http://live.gnome.org/LiveDocumentationEditing
Et les developeurs GTK+ ont parlé de sujets connexe récement:
http://mail.gnome.org/archives/gtk-devel-list/2009-February/(...)
Comme d'ab, il y beaucoup d'idées, et malheureusement beaucoup moins de dévelopeurs libres [de temps].
Je présume que ton aide serait grandement appréciée.
[^] # Re: En cogitation chez GNOME et GTK+
Posté par jm trivial (site web personnel) . Évalué à 2.
Dommage que la démo ne fonctionne pas.
# programmation lettrée
Posté par Gof (site web personnel) . Évalué à 2.
Existe t il un seul projet utile réellement réalisé en suivant ce modèle ?
[^] # Re: programmation lettrée
Posté par jm trivial (site web personnel) . Évalué à 2.
http://www.demexp.org/dokuwiki/fr:telechargement_du_logiciel(...)
# mode vendredi
Posté par BAud (site web personnel) . Évalué à 2.
(ou alors envoyer tes patchs pour que ça remonte vers les projets upstream directement, comme quoi, en libre ça permettrait des choses hein...)
Suivre le flux des commentaires
Note : les commentaires appartiennent à celles et ceux qui les ont postés. Nous n’en sommes pas responsables.