I siti della documentazione sia di Ruby core che di rails fanno
letteralmente cagare. Non ho ancora trovato nessuno che rende le api
cercabili in maniera decente. E’ il punto più debole sia del
linguaggio che del framework, secondo me. Le info ci sono, le
spiegazioni sono spesso sufficienti, ma quante volte mi sono
frustrato
a cercarla… I docs di PHP sono un miliardo di volte meglio.
Qualcuno sa dove sono finiti i vari proggetti di miglioramento della
documentazione circolavano con tutti quei soldi raccolti dalla
communità l’autunno scorso? Come hanno deciso di spenderli alla fine?
E il risultato? Mi sono perso qualcosa o effettivamente non s’è
(ancora) visto nulla?
:-/
david wrote:
I siti della documentazione sia di Ruby core che di rails fanno
letteralmente cagare. Non ho ancora trovato nessuno che rende le api
cercabili in maniera decente. E’ il punto più debole sia del
linguaggio che del framework, secondo me. Le info ci sono, le
spiegazioni sono spesso sufficienti, ma quante volte mi sono
frustrato
a cercarla… I docs di PHP sono un miliardo di volte meglio.
Qualcuno sa dove sono finiti i vari proggetti di miglioramento della
documentazione circolavano con tutti quei soldi raccolti dalla
communità l’autunno scorso? Come hanno deciso di spenderli alla fine?
E il risultato? Mi sono perso qualcosa o effettivamente non s’è
(ancora) visto nulla?
:-/
mah… daje tmepo, php esiste da una vita… certo
finche’ la gente contnua a tirarsela con sto rails… piuttosto
invece di fare pubblicita’ che inizino a fare della buona doc anche se
ci vorra’ tempo 
-_- a me smebra na rosicata bella e buona, il manuale di php è
perfetto, la doc di rails non può reggere il confronto… a volte
bisogna accettare la realta’…
Se non mi ricordo male anche PHP 3 era ben documentato… Ad un certo
punto l’autunno scorso hanno raccolto $15000 per migliorare la
documentazione e - almeno io - non ho visto nulla uscire da quella
campagna. Il minimo sarebbe dire “Ok, con questi soldi vogliamo fare
X
e, pian piano e con i tempi nostri, lo stiamo facendo”.
PHP è un po’ più facile da documentare, è vero. È un’API procedurale
dove ogni pezzo può essere documentato per conto proprio. Rails è
diverso (lo so che sto confrontando un linguaggio con un framework,
ma
please bear with me) e molti pezzi interagiscono tra loro. Il
difficile sta proprio nel documentare questa interazione. Si vede
dalle domande che sorgono su questa ML: la domanda sulla RAILS_ROOT
di
qualche giorno fa è un buon esempio. Dove si trova informazione del
genere?? O il nuovo routing di 1.2? Sono diventato scemo prima di
riuscire a mettere insieme i pezzi dai vari blogpost. Sono sicuro che
la policy di non accettare patch senza test è un’ottima cosa, ma
accettare patch/commit senza documentazione??? Per me è francamente
più importante che sia documentato che testato. Meglio entrambi, ma se
proprio dovessi scegliere…
Il codice di Rails è molto leggibile, certo, ma non è mica una
sostituzione alla documentazione.
Alex E. wrote:
david wrote:
I siti della documentazione sia di Ruby core che di rails fanno
letteralmente cagare. Non ho ancora trovato nessuno che rende le api
cercabili in maniera decente. E’ il punto più debole sia del
linguaggio che del framework, secondo me. Le info ci sono, le
spiegazioni sono spesso sufficienti, ma quante volte mi sono
frustrato
a cercarla… I docs di PHP sono un miliardo di volte meglio.
Qualcuno sa dove sono finiti i vari proggetti di miglioramento della
documentazione circolavano con tutti quei soldi raccolti dalla
communità l’autunno scorso? Come hanno deciso di spenderli alla fine?
E il risultato? Mi sono perso qualcosa o effettivamente non s’è
(ancora) visto nulla?
:-/
mah… daje tmepo, php esiste da una vita… certo
finche’ la gente contnua a tirarsela con sto rails… piuttosto
invece di fare pubblicita’ che inizino a fare della buona doc anche se
ci vorra’ tempo 
_______________________________________________________________________
Ml mailing list
[1][email protected]
[2]http://lists.ruby-it.org/mailman/listinfo/ml
–
“Man lär så länge man lever. Man lär så länge man har en lever.”
References
On 1/29/07, stb [email protected] wrote:
cmq i discorsi tipo “php esiste da una vita ecc” sono cagate se uno fa
un framework/linguaggio devo prima di tutto fornire la doc.
Uhm… “deve”?
Rails è ancora libero e gratuito. Anche a me farebbe piacere migliore
documentazione, cerchiamo di non perdere la bussola però. 
–
Massimiliano M.
code: http://dev.hyperstruct.net
blog: http://blog.hyperstruct.net
E’ da quando ho iniziato con Rails/Ruby che lo dico, forse è proprio per
quello oltre che per la sintassi strana che Rails/Ruby è così ostile.
cmq i discorsi tipo “php esiste da una vita ecc” sono cagate se uno fa
un framework/linguaggio devo prima di tutto fornire la doc.
Alex E. wrote:
-_- a me smebra na rosicata bella e buona, il manuale di php è
perfetto, la doc di rails non può reggere il confronto… a volte
bisogna accettare la realta’…
Scusate ma forse io sono duro di comprendorio… a prescindere che PHP
è da
tanti anni che ormai esiste bla bla bla,
Cosa mi significa: visto che Ruby è gratuito non è necessario rilasciare
documentazione…
Anche PHP è gratuito, e comunque documentazione ce n’è, ci sono contributi
degli utenti che per determinate esigenze sfruttano la specifica
funzione e
dimostrano come usarla. Ma quello e PHP ed è da tanto che esiste? Non sta
in
piedi. La documentazione di base è uscita insieme al prodotto, le nuove
versioni vengono rilasciate corredate di documentazione.
Un buon prodotto oltre ad essere funzionale, versatile, flessibile,
adattabile, dalla curva di apprendimento rapido, e chi più ne ha più
ne
metta, deve, ed evidenzio DEVE, essere corredato di buona
documentazione,
altrimenti:
- Perde di valore il prodotto stesso,
- Non potrà essere appreso da tutti ma solo da chi ha tanto, ed anche
qui evidenzio TANTO, tempo da perdere in test, prove e smanettonerie
varie.
Anche a me farebbe piacere farlo, ma purtroppo non ce l’ho.
Con questo non dico che Ruby non sia valido o che RoR sia scadente ma
perdono di qualità e non gli viene attribuito il giusto valore proprio
perchè carenti di documentazione.
Vi prego di correggermi se sto dicendo delle baggianate… anzi ne sarei
seriamente onorato!
Grazie e buon lavoro a tutti!
Diego La Monica
Analista programmatore
Programmazione, Standards ed Accessibilità
Membro: IWA Italy
Via Napoli, 5 - Loc. la Scala
56028 San Miniato (PISA)
tel. (+39) 0571464992
cell. (+39) 3337235382
e-mail: [email protected]
skype: diego.la.monica
ICQ #: 249-460-264
web: http://dlamonica.netsons.org
Scusate ma forse io sono duro di comprendorio… a prescindere che PHP
è da
tanti anni che ormai esiste bla bla bla,
Cosa mi significa: visto che Ruby è gratuito non è necessario rilasciare
documentazione…
Anche PHP è gratuito, e comunque documentazione ce n’è, ci sono contributi
degli utenti che per determinate esigenze sfruttano la specifica
funzione e
dimostrano come usarla. Ma quello e PHP ed è da tanto che esiste? Non sta
in
piedi. La documentazione di base è uscita insieme al prodotto, le nuove
versioni vengono rilasciate corredate di documentazione.
Un buon prodotto oltre ad essere funzionale, versatile, flessibile,
adattabile, dalla curva di apprendimento rapido, e chi più ne ha più
ne
metta, deve, ed evidenzio DEVE, essere corredato di buona
documentazione,
altrimenti:
- Perde di valore il prodotto stesso,
- Non potrà essere appreso da tutti ma solo da chi ha tanto, ed anche
qui evidenzio TANTO, tempo da perdere in test, prove e smanettonerie
varie.
Anche a me farebbe piacere farlo, ma purtroppo non ce l’ho.
Con questo non dico che Ruby non sia valido o che RoR sia scadente ma
perdono di qualità e non gli viene attribuito il giusto valore proprio
perchè carenti di documentazione.
Vi prego di correggermi se sto dicendo delle baggianate… anzi ne sarei
seriamente onorato!
Grazie e buon lavoro a tutti!
–
Diego La Monica
Analista programmatore
Programmazione, Standards ed Accessibilità
Membro: IWA Italy
Via Napoli, 5 - Loc. la Scala
56028 San Miniato (PISA)
tel. (+39) 0571464992
cell. (+39) 3337235382
e-mail: [email protected]
skype: diego.la.monica
ICQ #: 249-460-264
web: http://dlamonica.netsons.org
stb wrote:
E’ da quando ho iniziato con Rails/Ruby che lo dico, forse è proprio per
quello oltre che per la sintassi strana che Rails/Ruby è così ostile.cmq i discorsi tipo “php esiste da una vita ecc” sono cagate se uno fa
un framework/linguaggio devo prima di tutto fornire la doc.Alex E. wrote:
-_- a me smebra na rosicata bella e buona, il manuale di php è
perfetto, la doc di rails non può reggere il confronto… a volte
bisogna accettare la realta’…
emmm non ho capito, appunto devono fornire la doc e qui raill casca
insieme all’asino XD
On 1/29/07, Diego La Monica [email protected] wrote:
Scusate ma forse io sono duro di comprendorio… a prescindere che PHP è da
tanti anni che ormai esiste bla bla bla,
Cosa mi significa: visto che Ruby è gratuito non è necessario rilasciare
documentazione…
Interpretazione arbitraria.
Vi prego di correggermi se sto dicendo delle baggianate… anzi ne sarei
seriamente onorato!
Nessuna baggianata. Personalmente, finché il mio portafoglio rimarrà
chiuso nei confronti di Matz, DHH, e amici, mi guarderò bene dal dire
che hanno il dovere di usare il loro tempo come ritengo opportuno io.
–
Massimiliano M.
code: http://dev.hyperstruct.net
blog: http://blog.hyperstruct.net
Io quando rilascio procedure (che siano free o commerciali non conta)
rilascio documentazione.
Sarà più o meno autorevole, più o meno dettagliata (ma solo perchè do per
scontato dei concetti) ma non si sta parlando di quel che faccio io.
Ho detto semplicemente quello che pensavo e non volevo offendere
nessuno.
Solo che si continua a decantare Ruby, RoR e non so cosa altro ma io non
sono riuscito ancora ad avvicinarmi al linguaggio proprio per il
problema
riscontrato (non solo da me) sulla lista: scarsità di documentazione.
Ribadisco: ruby non metto in dubbio (e non è questo l’argomento su cui
verte
il post) possa essere il linguaggio del futuro, e tantomeno sia migliore
o
peggiore di un altro linguaggio (in merito c’è stato un post negli ultimi
giorni), ma credo sia carente di documentazione e lo hanno segnalato
altri
prima di me.
E di certo non credo di aver puntato il dito verso qualcuno (e tantomeno
verso te) chiedendo “Tu cosa fai per migliorarla?”. Io non ho fatto
nulla ma
questo non vuol dire che non possa avere un parere in merito. Varrà zero
solo perchè non ho scritto nulla in merito? Non saprei da dove cominciare,
non conosco il linguaggio e farei peggio che esprimere una mia critica
(tra
l’altro costruttiva) volta a chiarire che un prodotto sarà anche il
migliore
del mondo ma perde di qualità senza documentazione.
Spero di essere stato più chiaro, rispetto all’ultimo messaggio.
On 29/01/07, David W. [email protected] wrote:
–
Diego La Monica
Analista programmatore
Programmazione, Standards ed Accessibilità
Membro: IWA/HWG International
Via Napoli, 5 - Loc. la Scala
56028 San Miniato (PISA)
tel. (+39) 0571464992
cell. (+39) 3337235382
e-mail: [email protected]
skype: diego.la.monica
ICQ #: 249-460-264
web: http://dlamonica.netsons.org
Piaaaaaano tutti…
Ho solo domandato che fine avessero fatto i soldi raccolti allo scopo
di migliorare una situazione che - credo - tutti sono d’accordo a
chiamare “subottimale”…
- Non avendo contribuito alla raccolta le mie sono solo lagne.
- Nessuno deve documentare un progetto Open Source. Ovviamente.
- La documentazione esiste. È pessima, ma c’è. Preferisco sbattermi
per trovare le info e ottenere un risultato bello, elegante e
“corretto” al mondo PHP dove c’è uno snippet di codice per ogni cosa
che bene o male funziona e che rende il risultato finale una zuppa
puzzolente di codice. - Con una documentazione ai livelli di PHP, RoR farebbe un grosso
passo in avanti…
Massimiliano M. wrote:
On 1/29/07, Diego La Monica [1]<[email protected]> wrote:
Scusate ma forse io sono duro di comprendorio... a prescindere che
PHP è da
tanti anni che ormai esiste bla bla bla,
Cosa mi significa: visto che Ruby è gratuito non è necessario
rilasciare
documentazione...
Interpretazione arbitraria.
Vi prego di correggermi se sto dicendo delle baggianate... anzi ne
sarei
seriamente onorato!
Nessuna baggianata. Personalmente, finché il mio portafoglio
rimarrà
chiuso nei confronti di Matz, DHH, e amici, mi guarderò bene dal
dire
che hanno il dovere di usare il loro tempo come ritengo opportuno
io.
–
“Ce qui compte, ce n’est pas le bonheur de tout le monde, c’est le
bonheur de c
hacun.” - Boris Vian
References
E` vero che potrebbe essere migliorata la documentazione.
Tu cosa fai per migliorarla?
–
David N. Welton
Linux, Open Source Consulting
Stefano C. wrote:
On Jan 12, 2007, at 10:52 AM, david wrote:
della
documentazione circolavano con tutti quei soldi raccolti dalla
communit� l’autunno scorso? Come hanno deciso di spenderli alla
fine?
E il risultato? Mi sono perso qualcosa o effettivamente non s’�
(ancora) visto nulla?
:-/A parte che la documentazione di Rails non fa cosi’ schifo…
A parte che per forza la documentazione di PHP e’ un miliardo di
volte meglio,
deve sopperire al fatto che PHP e’ un miliardo di volte peggio
Detto questo,
http://caboose.stikipad.com/documentation/show/HomePage
http://caboo.se/doc.html–
Stefano C.
[email protected]
i bambini dell’asilo… e’ meglio qui e’ melgio li… non
c’entra una fava che php si apegigo o meglio, perhce’ non era questo il
topic, l’argomento e’ che ha una doc abbastanza pietosa ed e’ vero, ora
tu dici “PHP merda” ma non siparlava di questo, ritengo questo post
fuori luogoe inopportuno
e poi prima di dire merda a una cosa solo perche’ alcuni guru se
mettonoa di’ ste cazzate o in chat usala fino a fondo…
alla fine rails a me non sembra nulla di fiko, ma non per questo dico
che e’merda da FANATICO 
On Jan 12, 2007, at 10:52 AM, david wrote:
della
documentazione circolavano con tutti quei soldi raccolti dalla
communità l’autunno scorso? Come hanno deciso di spenderli alla
fine?
E il risultato? Mi sono perso qualcosa o effettivamente non s’è
(ancora) visto nulla?
:-/
A parte che la documentazione di Rails non fa cosi’ schifo…
A parte che per forza la documentazione di PHP e’ un miliardo di
volte meglio,
deve sopperire al fatto che PHP e’ un miliardo di volte peggio 
Detto questo,
http://caboose.stikipad.com/documentation/show/HomePage
http://caboo.se/doc.html
–
Stefano C.
[email protected]
Ruby poi è un’ altra cosa, la doc è fatta bene, basta abituarsi.
Vero. Lo standard lib e molti gem ecc sono ben documentati. Non
benissimo forse, ma adeguato.
Uhm… “deve”?
Rails è ancora libero e gratuito. Anche a me farebbe piacere migliore
documentazione, cerchiamo di non perdere la bussola però.
–
“Notre malheur n’atteint son plus haut point que lorsque a été envisagée,
suffisamment proche, la possibilité pratique du bonheur.” - Michel
Houellebecq
ho capito che è libero e gratuito ma ciò non vuol dire niente.
La mia è una critica, ritengo Rails splendido ma per diffondersi ha
bisogno
di essere documentato come si deve.
Ruby poi è un’ altra cosa, la doc è fatta bene, basta abituarsi.
----- Original Message -----
From: “Massimiliano M.” [email protected]
To: [email protected]
Sent: Monday, January 29, 2007 12:35 PM
Subject: Re: [ruby-it] Re: Re: Ruby docs, rails docs => miseria
On 1/29/07, stb [email protected] wrote:
cmq i discorsi tipo “php esiste da una vita ecc” sono cagate se uno fa
un framework/linguaggio devo prima di tutto fornire la doc.
Uhm… “deve”?
Rails è ancora libero e gratuito. Anche a me farebbe piacere migliore
documentazione, cerchiamo di non perdere la bussola però.
–
Massimiliano M.
code: http://dev.hyperstruct.net
blog: http://blog.hyperstruct.net
Ml mailing list
[email protected]
http://lists.ruby-it.org/mailman/listinfo/ml
pensoc he tutti andiamo li per la doc, ma il punto è che non è completa,
mancano un sacco di dettagli.
----- Original Message -----
From: “Matteo V.” [email protected]
To: “ruby-it” [email protected]
Sent: Monday, January 29, 2007 5:13 PM
Subject: Re: [ruby-it] Ruby docs, rails docs => miseria
On 1/29/07, Stefano C. [email protected] wrote:
On Jan 12, 2007, at 10:52 AM, david wrote:
I siti della documentazione sia di Ruby core che di rails fanno
letteralmente cagare. Non ho ancora trovato nessuno che rende le
api
cercabili in maniera decente. E’ il punto più debole sia del
Io vado su http://api.rubyonrails.com/, digito mela-F seguito da (per
esempio) has_many e arrivo sulla documentazione che mi serve. E’
semplice e funzionale. Ancora meglio: mi sono generato la doc sul mio
computer, in modo da consultarla senza andare su Internet.
A parte che la documentazione di Rails non fa cosi’ schifo…
Bravo! Prima di lamentarvi, provate a consultare la doc ufficiale.
Le funzioni pubbliche di rails sono tutte documentate. E in cima al
file dove appaiono, c’è anche una discussione generale sul perché e il
percome delle api di quel file. Secondo me Rails ha avuto una
documentazione di molto buon livello fino dalla prima release che ho
visto.
Posso capire l’obiezione che non c’è sufficiente documentazione di
tipo tutorial. Non so se questa obiezione sia ancora valida, dato che
un po’ di tutorial free esistono. Resta il fatto che puoi comprare il
libro di Thomas e DHH per poche decine di euro. E ci sono sei o sette
altri libri.
A parte che per forza la documentazione di PHP e’ un miliardo di
volte meglio,
deve sopperire al fatto che PHP e’ un miliardo di volte peggio
Infatti! La doc di PHP è importante soprattutto perché le api di PHP
hanno un comportamento inconsistente da funzione a funzione, e da
release a release. E perché spesso la funzionalità fornita è
incompleta, e alcuni volenterosi forniscono workaround.
Il fatto è che Rails sì, ti vuole rendere la vita semplice, ma assume
che tu sia smart. Per cui DHH non sta a preoccuparsi troppo del
fatto che la sintassi di Ruby sia “strana”. Se non conosci Ruby, sta
a te darti da fare per impararlo. Le risorse ci sono. Stesso
discorso per le (poche) funzioni che non sono documentate. Basta
cliccare su “view source” e si capisce come funzionano. Se ti scoccia
troppo questa cosa, forse Rails non è per te. DHH non ha mai detto
che Rails sia per tutti. Dopo tutto, è codice opinionato.
Chiaro che ci possono essere dei dettagli che comunque non restano
chiari, come ad esempio il dubbio su RAILS_ROOT. Però non è che ci
voglia tanto per aggiungere una mezza paginetta di documentazione sul
wiki di rails. Se nessuno lo fa, vorrà dire che il problema non è
così sentito.
Matteo
Ml mailing list
[email protected]
http://lists.ruby-it.org/mailman/listinfo/ml
Massimiliano M. wrote:
Vi prego di correggermi se sto dicendo delle baggianate… anzi ne sarei
seriamente onorato!Nessuna baggianata. Personalmente, finché il mio portafoglio rimarrà
chiuso nei confronti di Matz, DHH, e amici, mi guarderò bene dal dire
che hanno il dovere di usare il loro tempo come ritengo opportuno io.
D’accordo al 100%, o come ha detto DHH a alla Rails conference:
Vendoritis.symptoms = %w[Entitlement Indignation]
Vendoritis.treatments = [
Range(‘Fuck You’…‘Yes Massa’)
Range(‘Sarcasm’…‘Umor’)]
DHH.translate(MIT_LICENSE)
=> “I DON’T OWE YOU SHIT!”
(N.B. il suo “rant” sulla malattia che stava aggredendo la comunita
degli sviluppatori Rails era una risposta alle reazioni riguardo il baco
di sicurezza riparato in un paio di giorni, ma tant’e’…)
Luca
–
Web: http://spazidigitali.com - http://thetyper.com
Email mailto://[email protected]
Skype callto://l.mearelli
stb wrote:
pensoc he tutti andiamo li per la doc, ma il punto è che non è
completa, mancano un sacco di dettagli.
Scusate, ma perchè non cercate di quotare un pochino i messaggi ?
Passi la diatriba fra top-middle-bottom posting, passino i messaggi dove
i
caratteri accentati scompaiono (con buona pace della compresnione del
testo), ma almeno un minimo di netiquette.
Sui 20" con mua tridimensionali, non da alcuna preoccupazione il tutto,
ma
per chi legge le mail via client testuale o sul
palm/cell/smartphone/topogigio, non è così scontata la faccenda.
=D
oooO Oooo
( ) YUS ( )
\ ( Para todos, todo, ) /
_ ) nada para nosotros. ( _/