[Docs] Infrastuttura per la gestione della documentazione

[Manlio Perillo]

Alan Franzoni ha scritto:
> 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.
> 

Ok, allora la cosa va approfondita.

> 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. 

Gli script che ho scritto (con tanta fatica :)), fanno proprio questo.
Suddividono un nuovo documento da tradurre in N linee, ma non spezzano i 
paragrafi.

Le varie parti sono segnalate tramite marcatori,

> 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.
> 

Si, è interessante.
Magari si può integrare con quanto ho già scritto io e scrivere una 
applicazione web riutilizzabile anche da altri progetti di traduzione.

Il discorso va approfondito.

> 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... 

Tradurre non usando il formato originale non mi pare una idea furba.

> 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).
> 

Includi anche me :).

> 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.
> 

Spero solo che al Pycon si trova il tempo per discutere anche di questo.



Saluti  Manlio Perillo