manuale tecnico aggiornabile

renareto” post=76860Ciao a tutti,
nel posto dove lavoro (una softwarehouse), devo sviluppare un manuale (una parte via…:smile: ) del prodotto di questa azienda, che è un sw molto complesso in termini di “feature”.

Visto che sono un amante di latex, mi sono detto: esisterà qlc cosa che mi permetta di:
– redigere il manuale
– averlo in .pdf
– ma soprattutto consentire l’ aggiornamento facilmente anche a chi non è esperto.

Pensavo ad una cosa del genere:
I contenuto in un DB, facilmente aggiornabile e la forma in latex.

Sto dicendo una castronria?

Grazie

Renato

No. Secondo me non dici castronerie. Però…
Il testo tuttavia, potrebbe dover contenere mark up, per esempio per enfatizzare una parola, ed il mark up finirebbe anch’esso nel db.
Tanto vale lasciare in chiaro il contenuto realizzando al posto di un database una classe di documento con le impostazioni necessarie, che poi carichi i file necessari.
Invece di lavorare con lo scomodo db, si lavora con i classici file di testo, molto semplici da aggiornare ed archiviare.

Anzi, potresti pensare di utilizzare un repository git su cui caricare i commit, utile per un lavoro di gruppo, oppure pensare di scrivere il manuale direttamente nei sorgenti, per esempio come javadoc, “literate programming”.
Uno script ad hoc, potrebbe ricavare i sorgenti LaTeX direttamente dal codice. L’onere della gestione delle revisioni sarebbe risolto automaticamente dal sistema di gestione dei sorgenti, mentre lo sviluppatore è quello che conosce al meglio il software, e scrivendone la documentazione potrebbe lui stesso ricavarne utili miglioramenti.
In generale, terrei il testo in file di testo, eventualemente gestendo un repo su db per il controllo delle revisioni.
R.

renareto” post=76863No, ma intendi, non è che io voglia usare il DB! anzi! E’ che pensavo a questo come repo “ufficiale”. Invece, tu dici:
– fai tutto con dei file di testo
– li carichi su un GIT per il versioning
– i singoli programmatori aggiornano la parte che gli serve
– una persona (io) si incarica di compilare il tutto, quando serve il manuale

Una cosa del genere?

Renato

Potrebbe essera la soluzione. Tieni conto che io uso questo metodo per scrivere le guide tematiche del GuIT.
Uso github per i repo pubblici o bitbucket se deve rimanere segreto! Nulla vieta di far girare git sulla rete LAN.
Nel tuo caso, ognuno avrebbe il proprio repo personale con GIT ed interverebbe sulle parti di proprio interesse, poi un coordinatore riceve i commit del brach principale, gestisce i casi di conflitto e cura la compilazione.
Secondo me, alla fine ti è necessario anche un file di classe apposito per il tuo manuale, che si occupi di definire layout, loghi ambienti particolari per comporre reference di comandi per esempio, ecc

Rimane da esplorare la questione del literate programming (scrivere la doc direttaemnte nei sorgenti).
Parlatene.
R.

Naturalmente usare gli hyperlink renderà molto felici gli utenti (pacchetto hyperref).
Naturalmente inoltre, potreste lavorare ad una prima versione su LaTeX del manuale per poi sviluppare la soluzione più opportura (git o altro).
R.

renareto” post=76875Ma non esisterà qlc cosa di già fatto?

Mi vengono in mente due progetti: il Debian Administrator’s Handbook e l’Ubuntu Manual. Sono entrambe delle guide ed entrambe hanno come output finale un PDF (il manuale di Debian anche HTML e vari formati di ebook). L’Ubuntu manual usa sicuramente LaTeX, la guida di Debian credo di no (ma il risultato finale è comunque piacevole). Non ho seguito questi progetti, non saprei spiegarti come funzionano, però puoi dare un’occhiata ai codici:
`$ git clone git://anonscm.debian.org/debian-handbook/debian-handbook.git # per il manuale di Debian
$ bzr branch lp:ubuntu-manual # per il manuale di Ubuntu`Se non vuoi scaricare gli interi repository puoi visitare i siti
http://anonscm.debian.org/gitweb/?p=debian-handbook/debian-handbook.git;a=tree
https://code.launchpad.net/ubuntu-manual

renareto” post=76932Scusa,
sto cercando informzioni sulla piattaforma che viene utilizzata per produrre questo materiale (l’ idea mi piace molto). Visto che si trata di un progetto Open source, immagino si possa utilizzare.

Chi sa darmi qlc dritta?

Grazie

Renato

“questo”… quale? Le due guide di Debian e Ubuntu? Se la risposta è sì, qui trovi il Makefile usato per compilare la guida di Debian, qui per quella di Ubuntu. Come vedi, per la seconda si è usato essenzialmente XeLaTeX, le grosse complicazioni sono legate al fatto che la guida deve essere tradotta in più lingue e per fare questo fanno uso di gettext, ma penso che questo non dovrebbe interessarti. Per quanto riguarda la guida di Debian, invece, fa uso di Publican per la versione HTML, dblatex per tradurre il sorgente DocBook in LaTeX.

Comunque il workflow dovrebbe essere quello che immaginavi tu: sorgente su un sistema di versioning (git in un caso, bazaar nell’altro), un coordinatore che gestisce il repository principale, tanti fork che poi effettuano i pull nel repository principale

renareto” post=76953

“questo”… quale? Le due guide di Debian e Ubuntu?

scusa, hai ragione, intendevo quello di Ubuntu.

Ma i link che mi hai dato, di cosa sono? del sorgente per creare l’ambiente?

Quali link in particolare? I primi due rimandavano ai Makefile delle due guide, gli ultimi tre ai siti di Publican, dblatex e DocBook, nel caso tu non conoscessi questi progetti (per esempio io non li conoscevo). DocBook ha voce su Wikipedia in inglese, sembra un linguaggio molto interessante perché senza cambiare il sorgente permette di ottenere un documento in molti formati differenti (Wikipedia elenca HTML, XHTML, EPUB, PDF, pagine di manuali Unix, Web help e CHM) senza modificare il sorgente. Da questo punto di vista LaTeX è in netto svantaggio, ma ciò è dovuto al fatto che LaTeX è nato per fare altro e lo fa molto bene. Il difetto di DocBook è che non si appoggia direttamente su LaTeX, però con dblatex è possibile tradurre un sorgente DocBook in LaTeX e poi apportare le volute modifiche. Se preferisci avere la tua guida in HTML e PDF credo che DocBook sia una buona soluzione, non per niente “Doc” sta per “Documentation” e l’incipit della voce di Wikipedia dice

WikipediaDocBook is a Semantics markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation.

renareto” post=76953hai anche un link per vedere come funziona?

Ti ho dato i link ai repository dei due progetti, cosa ti serve altro di preciso? Tieni presente che se non hai intenzione di tradurre il tuo manuale in più lingue il lavoro si semplifica notevolmente, diventa un semplice repository con il sorgente LaTeX e basta. Eventualmente puoi aggiungere un Makefile o simile per automatizzare la compilazione.

Edit un altro linguaggio utile per la creazione di documentazione è Texinfo, utilizzato per la documentazione dei programmi del progetto GNU. Sviluppato da Karl Berry (che probabilmente qualcuno conoscerà), ha una sintassi vagamente simile a quella di LaTeX e permette di ottenere l’output in PDF, DVI, HTML, DocBook, XML e info. Sito del progetto, voce su Wikipedia

renareto” post=76960Ora guardo a DocBook e se esiste qlc sistema “collaborativo” per fare documentazione

Tutti i software di versioning (preferibilmente distribuiti) vanno bene, ti consiglierei bazaar, git o mercurial. git ha una comunità molto attiva (soprattutto grazie a github), mercurial è più adatto se ci sono utenti che usano Windows (infatti Mozilla ha scelto mercurial anche per questo motivo)