<html>
<head>
<meta content="text/html; charset=windows-1252"
http-equiv="Content-Type">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div class="moz-cite-prefix">On 06/01/2015 01:09 AM, David Costa
wrote:<br>
</div>
<blockquote cite="mid:20150601010950.1bc6b9af@inupik" type="cite">
<pre wrap="">
On 05/31/2015 07:59 PM, Nemesis wrote:
</pre>
<blockquote type="cite">
<pre wrap="">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.
</pre>
</blockquote>
<pre wrap="">
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 <a class="moz-txt-link-rfc2396E" href="mailto:iochesonome@gmail.com"><iochesonome@gmail.com></a> wrote:
</pre>
<blockquote type="cite">
<pre wrap="">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...
</pre>
</blockquote>
<pre wrap="">
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] <a class="moz-txt-link-freetext" href="http://gnuradio.org/redmine/projects/gnuradio/wiki">http://gnuradio.org/redmine/projects/gnuradio/wiki</a>
</pre>
</blockquote>
<br>
<font face="Helvetica, Arial, sans-serif">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
PDF<font face="Helvetica, Arial, sans-serif"><font
face="Helvetica, Arial, sans-serif"> o</font> epub</font></font>,
guardate qui in basso a sinistra: <a class="moz-txt-link-freetext" href="http://nodeshot.readthedocs.org/">http://nodeshot.readthedocs.org/</a><br>
<br>
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
<a class="moz-txt-link-freetext" href="https://docs.djangoproject.com/en/1.8/topics/signing/">https://docs.djangoproject.com/en/1.8/topics/signing/</a> ci sono tutte
le versioni (dev (ovvero master), 1.8, 1.7, 1.6, 1.5, 1.4).<br>
<br>
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.<br>
<br>
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.<br>
<br>
Io ve lo <b>ultraconsiglio</b><br>
<br>
Nemesis<br>
<br>
</body>
</html>