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

[David Costa]

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
-------------- parte successiva --------------
Un allegato non testuale è stato rimosso....
Nome:        non disponibile
Tipo:        application/pgp-signature
Dimensione:  801 bytes
Descrizione: OpenPGP digital signature
URL:         <http://ml.ninux.org/pipermail/bologna/attachments/20150601/c68faf32/attachment-0001.sig>