Autore Topic: Leggiamo la documentazione !  (Letto 4688 volte)

Offline md9327

  • Moderatore
  • Senatore Gambero
  • *****
  • Post: 2.840
    • Mostra profilo
Leggiamo la documentazione !
« il: 17 Marzo 2008, 02:37:36 »
Lo scrivo qui, che mi pare il posto giusto, anche se lo volevo inserire a seguito di una mia risposta in un'altra discussione.

Comunque, ripeto anche qui quello che ho accennato in altra discussione.
Leggiamo il manuale e proviamo a scrivere, solo così riusciamo a capire; se poi non ci si riesce, allora chiediamo aiuto.
Mi dispiace dire queste cose, ma a volte leggo domande e non ne comprendo il fine, forse perchè penso si sia incappati in qualche problema; poi vedo che il motivo della domanda è semplicemente perchè non si letta la documentazione.
La cosa mi dispiace e sconforta, perchè sò che il lavoro che stanno facendo le persone del team di Gambas non è semplice; a volte ho pure letto lamentele, magari anche senza cattivi fini, circa la mancanza di esempi pratici.
Bè, consideramo che queste persone non sono pagate e non lo fanno con fini di lucro, che occupano il loro tempo libero per creare e migliorare un software come è Gambas, trovano anche il tempo di scrivere la documentazione, che a mio avviso è anche meglio di altre commerciali.
Insomma, continuo a dire che mi dispiace scrivere queste righe, ma teniamo presente queste cose, e sfruttiamole! Diamo un senso al loro lavoro!

Scusate, ma ce l'avevo qui (sul pomo, tanto per dire :-) ).

Offline tornu

  • Gran Maestro dei Gamberi
  • *****
  • Post: 855
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #1 il: 17 Marzo 2008, 23:11:32 »
In linea di massima sono d'accordo con te, però vorrei porti un paio di domande e fare alcune considerazioni su quello che hai scritto.

Non ho capito di quale manuale parli, io ne sto cercando uno disperatamente, a parte la guida "Gambas beginners guide" non ho trovato altro, con tutte le difficoltà della lingua che penso non siano solo mie anche se ho appreso varie cose, se parli della guida inclusa in Gambas (sono uno di quelli che si è "lamentato") francamente non mi sembra molto esplicativa per chi come me è alle prime armi.
Altra documentazione in giro? Ti assicuro è pochina con tutte le ore che ho passato su Google a cercarne, sarebbe gradito se hai delle fonti farcele conoscere.

Nessuno penso si lamenti del lavoro del team Gambas, anzi penso che sia più che apprezzato l'impegno e il tempo che dedicano senza come tu fai notare percepire niente, penso che valga per qualsiasi progetto open souce.
Però io la penso così:
se crei un progetto open source è lo vuoi condividere e far conoscere alla comunità, è d'obbligo (secondo me) che sia fornito di una robusta documentazione in modo che gli altri possano capire e sfruttare al massimo il risultato del tuo impegno, altrimenti sarebbe fine a se stesso, che senso avrebbe?
Sono del parere che qualsiasi domanda venga posta meriti comunque una risposta, possono a volte sembrare banali e semplicistiche, non fornite di particolari o argomentate in modo non tecnico, ma tieni presente che sono persone appassionate, che magari non hanno una grande cultura informatica ma che comunque ci vogliono provare (vedi il sottoscritto) è che quello che per alcuni può sembrare semplice per altri è insormontabile.
Mi sbaglio o in generale i forum sono nati per dare un aiuto specialmente ai meno "esperti"?
E sempre bene esprimere ciò che si pensa quando si fa parte di una comunità e si condividono gli stessi interessi.

Scusate per la lungaggine.
Ciao
     :ciao:  :ciao:
Il software è come il sesso, è meglio quando è libero. (Linus Torvalds)

Offline fsurfing

  • Moderatore
  • Senatore Gambero
  • *****
  • Post: 2.484
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #2 il: 17 Marzo 2008, 23:53:06 »
mi associo a Tornu :-)

Offline leo72

  • Amministratore
  • Senatore Gambero
  • *****
  • Post: 2.163
    • Mostra profilo
    • http://www.leonardomiliani.com
Re: Leggiamo la documentazione !
« Risposta #3 il: 18 Marzo 2008, 08:49:56 »
Gambas è un ottimo progetto ma difetta enormemente in documentazione.
Già a suo tempo feci presente al team di sviluppo che, con l'uscita della 2.0. sarebbe stato meglio fermare lo sviluppo un mesetto e completare la documentazione.... e così non è stato... giù lavorano alla 3.0 quando apri la documentazione e trovi pagine e pagine non scritte.
Visita il mio sito personale: http://www.leonardomiliani.com

g.paolo

  • Visitatore
Re: Leggiamo la documentazione !
« Risposta #4 il: 18 Marzo 2008, 10:07:07 »
Anche io sono uno di quelli che si è lamentato, senza con con questo nulla togliere all'enorme merito che ha il team di sviluppo.
Condivido perfettamente quanto espresso da "tornu" perchè anche io mi comporto nel medesimo modo e passo ore ed ore alla ricerca di informazioni cercando di tradurre la scarna documentazione disponibile.
Egli ha scritto "fornito di una robusta documentazione in modo che gli altri possano capire e sfruttare al massimo il risultato del tuo impegno, altrimenti sarebbe fine a se stesso" ed aggiungo, che in tal caso il solo scopo ottenuto sarebbe quello di far esprimere al team frasi del tipo: "oh! che bel lavoro abbiamo fatto!"
Se il proposito vero è invece quello che gambas cresca, con una moltitudine di utilizzatori che passano a linux, la cosa giusta da fare sarebbe proprio quella espressa da "leo72", ed una volta risolti i bachi importanti, dedicarsi alla documentazione.
Questa operazione non sarebbe solo fine a se stessa, ma ricordo che quando desideri far capire a qualcuno come funziona una cosa, molto spesso impari aspetti nuovi della medesima che non avevi prima considerato, e nel caso di gambas, potrebbero venire a galla comportamenti anomali che aiuterebbero a risolvere bachi occulti.

Offline tornu

  • Gran Maestro dei Gamberi
  • *****
  • Post: 855
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #5 il: 18 Marzo 2008, 14:05:03 »
Un altro aspetto importante naturalmente è anche il nostro contributo che diciamo così in modo "trasversale" contribuisce a incrementare la documentazione ufficiale, nel senso quando rispondiamo ad una domanda perchè magari anche a noi e capitato lo stesso caso esposto è lo abbiamo risolto, cerchiamo di essere "semplici" il più possibile nell'esporre la soluzione e corredarla quando è il caso di esempi esplicativi, scusate se insisto in questo aspetto ma lo ritengo il modo più efficace per far capire ciò che vogliamo dire ai più, molto meglio di una esposizione teorica (serve anche quella).

Un'ultima cosa, un plauso a chi gestisce questo forum perchè comunque hanno cominciato a pubblicare tutorial e documentazione che speriamo cresca.

Facciamo crescere Gambas........yes we can......
Ciao
 :2birre:
Il software è come il sesso, è meglio quando è libero. (Linus Torvalds)

Offline md9327

  • Moderatore
  • Senatore Gambero
  • *****
  • Post: 2.840
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #6 il: 18 Marzo 2008, 20:33:17 »
Dalle vostre risposte credo di aver sollevato un bel vespaio, ma le mie parole sono state travisate.
Diciamo che la mia era in tema con il forum, ma per la parte suggerimenti, non di critica.
Il mio intento era quello di evidenziare alcune mancanze che, a mio avviso, vedo abbastanza frequenti, in questo e in altri campi, ovvero il domandare senza prima documentarsi.
Come alcuni di voi, giustamente ma purtroppo travisando il contenuto del mio post, hanno creduto che io volessi criticare la poca esperienza, oppure ancora una presunta mancanza di intelligenza di parte di alcuni, ma non è così.
Ho una certa età (o un'età certa...), e anche io ho fatto e avuto, e lo ammetto, ho imparato molto da chi è arrivato prima di me.
Cimunque, non voglio filosofeggiare inutilmente, come ho ribadito, la mia intenzione era quella di far presente che, alcune volte, si fanno delle domande che hanno già una risposta, bastava leggere due righe di manuale.
Non voglio fare riferimenti inutili, perchè come ho detto la mia non era critica bensì consiglio.
Dal canto mio, la mia poca esperienza la metto a disposizione, con umiltà e voglia di divulgare quello che sò, aiutare gli altri, specialmente quelli che iniziano ora; se dalle mie risposte nelle varie discussioni non si vede questa cosa, vuol dire che sbaglio qualcosa. L'idea di mettere qui il mio consiglio è stato appunto per non rispondere direttamente nelle altre discussioni, e solo per dire la mia a livello generale.

E per finire, questo sito, come altri, e le persone che lo gestiscono hanno tutta la mia ammirazione, e per quanto posso contribuisco e contribuirò sempre.

Chiedo scusa a chi si è sentito colpito nell'orgoglio, non era mia intenzione.

Offline fsurfing

  • Moderatore
  • Senatore Gambero
  • *****
  • Post: 2.484
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #7 il: 18 Marzo 2008, 21:24:52 »
Citazione
Dal canto mio, la mia poca esperienza la metto a disposizione, con umiltà e voglia di divulgare quello che sò, aiutare gli altri, specialmente quelli che iniziano ora; se dalle mie risposte nelle varie discussioni non si vede questa cosa, vuol dire che sbaglio qualcosa


Stai tranquillo md9327, il tuo aiuto secondo me e importantissimo, si vede benissimo la tua voglia ed il tuo interesse ad aiutare gli altri utenti (io per primo).
Continua così!!!!!!!!!
 :cappello:

Offline tornu

  • Gran Maestro dei Gamberi
  • *****
  • Post: 855
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #8 il: 18 Marzo 2008, 22:44:20 »
Anche da parte mia stai tranquillo non mi sono sentito colpito nell'orgoglio,va benissimo confrontarsi in modo costruttivo e mi associo all'incitamento di "fsurfing" nei tuoi confronti.
Ciao  :cappello:  :cappello:
Il software è come il sesso, è meglio quando è libero. (Linus Torvalds)

Offline leo72

  • Amministratore
  • Senatore Gambero
  • *****
  • Post: 2.163
    • Mostra profilo
    • http://www.leonardomiliani.com
Re: Leggiamo la documentazione !
« Risposta #9 il: 19 Marzo 2008, 02:06:29 »
Io sono tra coloro che non ho letto nelle tue parole critiche rivolte a nessuno in particolare. :2birre:
Anzi, alle volte fa piacere leggere di questi interventi perché fanno capire che la passione e l'interesse per una cosa sono grandi.

E ti confermo che il tuo appunto è stato assolutamente giusto. Se pensiamo che in un linguaggio di programmazione ciò che serve enormemente ai nuovi utenti sono proprio le info sul linguaggio stesso, capiamo quanto gli sviluppatori di Gambas dovrebbero soffermarsi a completare la documentazione prima di pensare a sviluppare Gambas3. Alla fine ci ritroveremo con un linguaggio che solo chi lo ha scritto potrà usarlo (paradossale ma non impossibile)   :leggere:
Visita il mio sito personale: http://www.leonardomiliani.com

g.paolo

  • Visitatore
Re: Leggiamo la documentazione !
« Risposta #10 il: 19 Marzo 2008, 09:33:37 »
Concordo pienamente con leo72! Su certe cose la documentazione potrebbe essere scritta in poche righe, magari con un semplicissimo esempio. Da parte mia sto raccoglienfo in un file tutti i suggerimenti e soluzioni che trovo durante il mio percorso didattico, comprendenti frammenti di codice, in modo che l'esperienza che sto facendo non vada persa nel dimenticatoio. Praticamente sto facendomi il manuale man mano che trovo le soluzioni ai problemi.

Offline md9327

  • Moderatore
  • Senatore Gambero
  • *****
  • Post: 2.840
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #11 il: 19 Marzo 2008, 20:51:20 »
Grazie, vedo che avete compreso le mie intenzioni.

Riguardo alla documentazione, sono pienamente d'accordo, alla fine diventa la cosa più importante per òa divulgazione di un bel progetto come Gambas.
Io, purtroppo, non ho molto tempo libero a disposizione, e quel poco lo dedico allo studio di cose nuove e, possibilmente, alla creazione di applicazioni open.
Questo perchè credo nell'open, e dall'open ho ricevuto molto.
Comunque, anche se questo ha bisogno di una certa base di conoscenze, se qualcuno ha la possibilità, potrebbe contribuire nel progetto; credo che il team di Benoit ne sarebbe felice. Non faccio parte del team, e quindi non faccio pubblicità, e per ovvii motivi il discorso è diretto a persone che hanno un pochino di domestichezza nel linguaggio, ma credo che qualcuno potrebbe già contribuire, anche solo per esporre alcune idee per migliorare la scarsa documentazione.

Offline Pixel

  • Amministratore
  • Maestro Gambero
  • *****
  • Post: 414
    • Mostra profilo
    • http://www.gambas-it.org
Re: Leggiamo la documentazione !
« Risposta #12 il: 20 Marzo 2008, 09:33:25 »
Leo aveva già esposto il problema nella ML di Gambas e la risposta di Benoit si può riassumere in:
ragazzi, io non ho tempo, se qualcuno vuol contribuire faccia pure

Dal mio punto di vista la cosa è più complessa di quanto sembri, è necessario considerare 2 fattori importanti:
1) Gambas è un linguaggio di programmazione
2) Gambas non è commerciale

1) Gambas è un linguaggio di programmazione
Il raggiungimento di un medesimo risultato si può ottenere in vari modi, ne consegue che se io scrivo documentazione e/o esempi di codice non è detto che siano la soluzione migliore. In teoria la strada maestra dovrebbe conoscerla Benoit o eventualmente lo sviluppatore di un particolare componente.

2) Gambas non è commerciale
Questo aspetto non trascurabile impedisce di spendere tempo per produrre informazione.

La mia convinzione è che progetti come Gambas-it o simili siano fondamentali nella divulgazione di Gambas e di eventuali risposte a dubbi sull'utilizzo.
Scriviamo micro codice, cerchiamo di commentarlo nel miglior modo possibile e mettiamolo on-line, è la soluzione (forse) più rapida e contestualmente meno onerosa per tutti.

Ovviamente dal mio punto di vista.
Ciao
Ubuntu Italian Member Ubuntu User 4683
Il mio Blog

Offline md9327

  • Moderatore
  • Senatore Gambero
  • *****
  • Post: 2.840
    • Mostra profilo
Re: Leggiamo la documentazione !
« Risposta #13 il: 20 Marzo 2008, 15:12:45 »
Perfetto pixel !!!

Hai riassunto in poche parole il concetto di base importantissimo.

Per il primo punto, era quello che immaginavo ritornasse dalla tua richiesta a Benoit. Purtroppo non si ha tempo di fare tutto, e non è solo per non si è pagati per il lavoro, ma proprio perchè stamo facendo un'altro lavoro dove ci pagano, per cui il tempo per l'open-gratis ne rimane poco. Non sò in quanti lavoano nel team in Gambas, ma presumo che non siano poi molti; se facciamo confronti con altri progetti open, es. python o perl, direi che sono proprio minimi...

Ritornando all'ultima parte del tuo post, riguardo gli esempi, ovviamente qualcuno di noi lo stà già facendo, inserendo codice nell'apposita sezione, e questa è già una bella cosa.

Per la documentazione, cerchiamo di riunire il più possibile le informazioni con le nostre discussioni, ma poi vediamo magari di riunirle in qualche sorta di guida generale, che ne dite ?

Offline Pixel

  • Amministratore
  • Maestro Gambero
  • *****
  • Post: 414
    • Mostra profilo
    • http://www.gambas-it.org
Re: Leggiamo la documentazione !
« Risposta #14 il: 20 Marzo 2008, 17:34:58 »
Molto bene, vedo con piacere che siamo tutti in sintonia :-D
Il core-team di Gambas si può ridurre a 4/5 persone (non considerando i traduttori).
Per quanto riguarda la documentazione mi hai letto nel pensiero e condivido al 100% questa possibile strada, unico appunto è che le informazioni e/o il codice dovrebbero rispondere a questi requisiti:
1. breve
2. chiaro
3. svincolato

breve: ovviamente non intendo che sia racchiuso in una riga (magari da 1000 caratteri) ma un codice corto presuppone una maggiore rapidità di esecuzione e di riflesso una maggiore comprensione da parte degli utenti

chiaro: non dobbiamo dare per scontato che se uno usa un linguaggio conosce anche tutti i comandi che ne fanno parte, quindi commentare il più possibile (ok.. if-then e for-next diamo per scontato di conoscerli)

svincolato: come estrarre una parola da una frase o come ridimensionare una form è consigliabile che siano trasformati in una funzione o una sub dove l'utente che ne farà uso si limiti a passare (esempio) nome_form, altezza, larghezza, posizione.

Ovviamente, considerate che sono opinioni personali e come tali discutibili.

P.S.
Precisazione: la domanda a Benoit in ML sul problema Documentazione l'ha posta Leo e non io. :-)
Ubuntu Italian Member Ubuntu User 4683
Il mio Blog