[Bologna] Documentazione (Era: Fwd: [lime-users] LiMe broken.)

[Nemesis]

On 06/01/2015 01:09 AM, David Costa wrote:
> On 05/31/2015 07:59 PM, Nemesis wrote:
>> Se posso permettermi di dare un consiglio, penso che la
>> documentazione in formato ResTructuredText o Markdown conservata in
>> un repository github sia la cosa migliore.
> Concordo anch'io sull'avere la documentazione in un repo.
> Se non è troppo grande può stare tranquillamente nello stesso repo del
> codice, così si possono versionare insieme e avere la documentazione di
> una release nello stesso commit di quella release.
>
>
> On Sun, 31 May 2015 20:33:02 +0200
> Ilario Gelmetti <iochesonome a gmail.com> wrote: 
>> Sarebbe figo, però ormai abbiamo iniziato a scriverla sui wiki e non
>> mi sembra affatto una buona idea spostarla/copiarla.
>> Eppoi il sito di libre-mesh ha anche la funzione wiki, mi sembra
>> naturale usarla per metterci la documentazione di libre-mesh...
> Il sito di libre-mesh è una istanza di Redmine e il wiki è una
> funzionalità davvero marginale di quel programma...
> le categorie non ci sono: si possono solo fare relazioni padre-figlio
> tra le pagine (e si fa con il tasto "rename"), e le categorie sono
> fondamentali nella documentazione per distinguere le pagine importanti
> tipo "routing in libre-mesh" da pagine molto specifiche o di reference
> ("how-to: compilare libre-mesh su PPC").
>
> Se vuoi portarti la documentazione off-line banalmente non puoi, a meno
> che non salvi tutte le pagine una per una perché non esiste nessun tool
> decente (e spero che qualcuno smentisca) per esportare il wiki
> intero o una categoria... quindi una volta che scrivi nel wiki di
> redmine non puoi migrare facilmente a niente di diverso, neanche un
> altro sito che usa redmine.
>
> Insomma, è per dire che il wiki di redmine non è un wiki normale, è una
> roba che serve solo per sopperire a esigenze di sviluppo o per dare
> link a risorse che non fanno parte della documentazione vera; per fare
> un esempio un progetto grosso che usa redmine dall'inizio alla fine è
> gnuradio [1], loro hanno nel wiki un po' di link a vari tutorial, dati
> d'esempio e pagine organizzative, ma il manuale vero è fatto con Doxygen
> e Sphinx (perché in realtà il bello di GNURadio sono le sue API).
>
> Capisco che avere un wiki permetta a più persone di scrivere qualcosa
> perché viene meno la sensazione di responsabilità che si avrebbe
> committando su un repo e perché è effettivamente più facile da usare,
> però che sia un wiki vero almeno, tipo dokuwiki o mediawiki :)
>
> Metto in CC lime-users perché credo che a questo punto, con diverse
> reti che vogliono iniziare _effettivamente_ ad usarlo converrebbe avere
> delle linee guida per la documentazione decise insieme agli
> sviluppatori.
>
> [1] http://gnuradio.org/redmine/projects/gnuradio/wiki

Inoltre avere la documentazione in formato testuale in un repo ti da la
possibilità di generarla in locale (se devi lavorare offline e
portartela appresso quando monti i nodi) o di generare altri formati,
come PDFo epub, guardate qui in basso a sinistra:
http://nodeshot.readthedocs.org/

Poi è più facile fare il versioning della documentazione, ovvero la doc
della versione 2 sarà diversa dalla versione 1, ad esempio guardate qui
in basso a destra https://docs.djangoproject.com/en/1.8/topics/signing/
ci sono tutte le versioni (dev (ovvero master), 1.8, 1.7, 1.6, 1.5, 1.4).

Poi non sono proprio daccordo che sul wiki sia più facile editare, se
uno non ha voglia di clonare il repo e farlo in locale puà farlo da
github ed è altrettanto facile, solo che invece usare la sintassi del
wiki si usa qualcosa che è leggermente più standard.

Insomma il vantaggio di avere la documentazione in questo formato è che
non si rimane legati ad un unico wiki, o a github o a readthedocs, si ha
il sorgente e poi i file si possono generare in tanti modi e ci sono
molti software già pronti che lo fanno molto bene.

Io ve lo *ultraconsiglio*

Nemesis

-------------- parte successiva --------------
Un allegato HTML è stato rimosso...
URL: <http://ml.ninux.org/pipermail/bologna/attachments/20150601/c3f0ce9e/attachment-0001.html>
-------------- parte successiva --------------
Un allegato non testuale è stato rimosso....
Nome:        signature.asc
Tipo:        application/pgp-signature
Dimensione:  473 bytes
Descrizione: OpenPGP digital signature
URL:         <http://ml.ninux.org/pipermail/bologna/attachments/20150601/c3f0ce9e/attachment-0001.sig>