[Docs] Infrastuttura per la gestione della documentazione

[Alan Franzoni]

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