[Docs] Infrastuttura per la gestione della documentazione

[Manlio Perillo]

Alan Franzoni ha scritto:
> Il 23/05/07, Manlio Perillo<manlio_perillo a libero.it> ha scritto:
>> Non dimentichiamo che avere la traduzione nello stesso formato del
>> documento originale ha molti vantaggi.
> 
> Il problema "solito" è che c'è poca gente dietro al tutto, e stare a
> tradurre un documento LaTeX porta via più tempo che tradurne uno in
> reST. 

Dipende da quale linguaggio conosci già.
Io conosco LaTeX e quindi non ho problemi.
Tu magari conoscevi già reST.

Bisognerebbe vedere i pareri di chi non conosce nessuno dei due.

> Perlomeno, io mi sto incasinando abbastanza con il LaTeX, sarà
> perché non lo conosco... ma non mi piace tanto ^_^
> 

Se è per questo, nemmeno a me piace molto :-).

> Da notare anche un'altra cosa: non mi risulta ci siano 'grandi
> traduzioni' in giro per il mondo fatte traducendo direttamente il
> .tex. Ho provato a cercare in giro, l'unico parte della doc tradotta
> in .tex è un tutorial in tedesco, fermo alla versione 1.5 di Python
> (anno 1999). Per il resto, gli altri documenti sparsi in giro per il
> mondo (ne ho guardati alcuni eh, non tutti!) sono creati con mezzi  e
> formati un po' a discrezione di chi fa la traduzione. Anzi, a dire la
> verità, devo dire che il corpus tradotto in italiano è già discreto
> per quanto riguarda la documentazione.
> 

Si, il precedende webmaster ha fatto un lavoro immenso.
Divideva i documenti in piccoli pezzi (a mano), e li passava ai 
traduttori convertendoli in semplice testo.

Quindi coordinava il tutto ed integrava.

Come si vede, se c'è la volontà si può fare tutto (il problema è che io 
non ne ho).

> Perciò, considerando che il convertitore rst2latex è già adesso parte
> delle docutils, e quindi una riconversione è comunque possibile... io
> voterei per passare a questo sistema anche per la documentazione.
> 

Io direi che è ancora troppo presto.
Come si dice: "chi lascia la vecchia via per la nuova, sa cosa lascia ma 
non sa quello che trova".

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

> Inoltre c'è un'altra idea che mi è 'saltata alla testa': dovremmo
> decidere una specie di 'coda di priorità' per quanto riguarda la
> traduzione. Leggendo quello che stavo traducendo, ovvero "Documenting
> Python", mi sono reso conto che è probabilmente uno degli ultimi
> documenti che quasi chiunque potrebbe leggere, in quanto spiega come
> documentare Python usando .tex. Essendoci svariati altri tool per la
> documentazione in giro, e pensando già io in primis di abbandonare
> latex, è probabilmente un documento che andrebbe perdendosi
> nell'inutilità.
> 
> Naturalmente non è che io dica che latex fa schifo ed è inutile; però
> abbiamo bisogno di massimizzare al 100% le nostre (scarse) risorse.
> 


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.


> Un programmatore scafato, inoltre, avrà al 99% una conoscenza più che
> buona dell'inglese, almeno tecnico, e non necessiterà affatto delle
> nostre traduzioni.
> 

Si.
Infatti io non credo molto nelle traduzioni.
Quando possibile cerco di studiare sempre sugli originali.

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

> Per il resto... be', ritengo davvero che sarebbe superfluo imbarcarsi
> in traduzioni. Le persone a cui potrebbero servire altri argomenti
> dovranno in ogni caso, necessariamente, impararsi quel tanto di
> inglese tecnico necessario a capire dove debbano andare a parare. In
> fondo, quando si passa ai corsi di informatica all'università o alla
> programmazione "professionale", è pressoché impossibile permettersi di
> non sapere l'inglese.
> 

Si, sono daccordo.
Per ora dobbiamo decidere se restare con LaTeX e chi può occuparsi a 
tempo pieno della coordinazione.



Saluti  Manlio Perillo