[Docs] Infrastuttura per la gestione della documentazione

Alan Franzoni alan.franzoni a gmail.com
Ven 25 Maggio 2007 19:11:25 CEST


Il 25/05/07, Manlio Perillo<manlio_perillo a libero.it> ha scritto:
> Tu magari conoscevi giÓ reST.

No... per˛ ci ho dato un'occhiata e mi sono "innamorato" subito. LaTeX
ancora non lo digerisco. Troppo macchinoso!

> E se in futuro ci accorgiamo dei limiti del nuovo formato, che si fa?
> Buttiamo tutto quello giÓ fatto?

No, come detto c'Ŕ rst2latex. A quel punto prenderemmo la versione
latex e ripartiremmo da quella.

Comunque ti do ragione sulla giovinezza della cosa; quindi mi riservo
di testare la conversione da/a latex entro il Pycon, in maniera da
poter dare un giudizio pi¨ obiettivo sulla cosa, senza stare a
discutere su una cosa che magari poi, all'atto pratico, Ŕ
impraticabile.

Tra l'altro: ho finalmente un serverino mezzo pronto online, volevo
proprio testare questo nuovo sistema di Brandl; non appena sono
riuscito a caricarlo e ad apportare le modifiche che vorrei vi mando
l'URL in lista

> Questo Ŕ vero.
> Per adesso quello che importa Ŕ aggiornare alla nuova versione, dalla 2.3.
>
> Assumendo 4 persone che aggiornano un documento al giorno, in qualche
> mese si conclude.

Io ho un'idea che avevo giÓ proposto ad Eriol. In linea con gli
obiettivi di Python Italia APS, vorrei fare una specie di campagna
'Adotta un pezzo di documento' al Pycon Uno.

In pratica, suddividendo la documentazione di Python non in linee
arbitrarie (che incasinano un po' tutto, IMHO) vorrei assegnare un
"mantainer" ad ogni capitolo, o sottocapitolo. Questo mantainer
dovrebbe avere accesso diretto, esclusivamente per la sua sezione, ad
un ipotetico (e ancora da definire) CMS per la documentazione di
python.it (docs.python.it) e mantenere aggiornata (direttamente) la
traduzione ad ogni versione. Se siamo d'accordo proporrei l'idea anche
sulla ML dell'organizzazione di Pycon.

Il coordinatore avrebbe quindi soltanto il ruolo di dare un'occhiata
alle traduzioni revisionate ed eventualmente sollecitare i mantainer o
assegnarne di nuovi quando i vecchi latitino.


> Quindi i documenti che sarebbe meglio avere sempre tradotti &
> aggiornati in italiano (alcuni dei quali sono giÓ pronti) sarebbero
> (IMHO):
> - Il tutorial di GVR
> - La library reference
> - Il nonprogrammer tutorial di Cogliati
> - Dive into Python
> - How to think like a computer scentist
> - Instant Python
>
> Il Dive into Python, purtroppo, Ŕ scritto in DocBook, Ŕ pure male (nel
> senso che non sembra scritto a mano, e quindi Ŕ complicato vedere cosa
> aggiornare).

Ma ci sono anche gli output in html, o in puro testo... non lasciamoci
prendere dalla foga del formato, l'importante Ŕ che, in un modo o
nell'altro, i contenuti ci siano. Da me si dice "il meglio Ŕ nemico
del bene". Quante volte per fare la "figata" si finisce per non
combinare nulla? Fin troppe, secondo me (e mi includo al 100% in
questa stima).

Per quanto riguarda il coordinamento, se riusciamo a mettere insieme
un buona infrastruttura e una buona squadra di mantainer per i
documenti - e quindi il tempo di coordinamento non diventa un secondo
lavoro a tempo pieno - io mi offro volontario. Certamente con
l'infrastruttura attuale il casino Ŕ davvero eccessivo.

In ogni caso mi pare fondamentale coinvolgere tutti i soci di Python
Italia nella gestione di python.it. D'altronde tale sito non diventerÓ
il sito 'istituzionale' dell'associazione? E' giusto non pressare
troppo prima del Pycon visto che c'Ŕ giÓ molto, moltissimo lavoro da
fare. Ma penso che il passo successivo sia proprio quello della messa
a punto di python.it.

-- 
Alan Franzoni <alan.franzoni a gmail.com>
-
GPG Key Fingerprint:
5C77 9DC3 BD5B 3A28 E7BC 921A 0255 42AA FE06 8F3E


Maggiori informazioni sulla lista Docs