[lime-dev] Fwd: [lime-users] Documentazione

Hey devs! On LiMe-Users mailing list there is a discussion on where to put the documentation of Libre-Mesh. It's long time that the lack of documentation _avoids_ people to try/join/enjoy the project. Returning to the email that I'm forwarding you, I will write a synopsis so you don't have to learn Italian for getting the concept: Federico: "documentation in ResTructuredText or Markdown on Github" David agrees Ilario: "too late, bad idea to move the documentation, wiki is ok" David: "wiki of Redmine = shit, if you want a wiki use a proper one" So? -------- Forwarded Message -------- Subject: Re: [lime-users] [Bologna] Documentazione (Era: Fwd: LiMe broken.) Date: Mon, 1 Jun 2015 01:09:50 +0200 From: David Costa <david.costa(a)ieee.org> Reply-To: libre-mesh users <users(a)lists.libre-mesh.org> To: bologna(a)ml.ninux.org CC: libre-mesh users <users(a)lists.libre-mesh.org> On 05/31/2015 07:59 PM, Nemesis wrote: 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: 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/wik