> 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.
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 Bastes . En réponse au journal Documentation collaborative. É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.