跳至第一个未读帖子
Mauro Cicolella
2016年5月27日 12:00:072016/5/27
收件人 Freedomotic - IoT and Smart Spaces Framework
Ciao a tutti
come è emerso nella discussione con Giuseppe la documentazione è al momento un punto critico del progetto.
Dunque è importante mettere a fuoco le problematiche e cercare di migliorarla il più possibile.
Per prima cosa la documentazione ufficiale é in inglese sul sito freedomotic.com e sul wiki https://github.com/freedomotic/freedomotic/wiki
Quindi una prima distinzione va fatta tra quella destinata agli utilizzatori finali (sul sito) e quella per gli sviluppatori (sul wiki).
Inoltre abbiamo un sito in italiano meno aggiornato a dire il vero. In questo caso la guida utente é costituita da http://freedomotic.sednet.it/argomenti/guide/installazione/ e da http://freedomotic.sednet.it/argomenti/guide/utilizzo/ mentre quella di sviluppo da http://freedomotic.sednet.it/argomenti/guide/sviluppo/
Dal mio punto di vista sarebbe utile avere anche un manuale in pdf consultabile offline.
E' chiaro che mantenere entrambe le modalità richiede un certo impegno.
Non mi piacerebbe dover fare ogni volta un copia/incolla per generare una nuova versione.
Sto cercando un modo per automatizzare il processo partendo dalle pagine su wordpress e sul wiki di github. Qualche idea?
Ricapitolando: se avete suggerimenti su come organizzare i contenuti, cosa vorreste aggiungere e come ottimizzare le risorse aggiungete i vostri commenti.
Naturalmente ogni contributo (revisione, stesura di guide ecc.) è ben accetto.
Mauro
come è emerso nella discussione con Giuseppe la documentazione è al momento un punto critico del progetto.
Dunque è importante mettere a fuoco le problematiche e cercare di migliorarla il più possibile.
Per prima cosa la documentazione ufficiale é in inglese sul sito freedomotic.com e sul wiki https://github.com/freedomotic/freedomotic/wiki
Quindi una prima distinzione va fatta tra quella destinata agli utilizzatori finali (sul sito) e quella per gli sviluppatori (sul wiki).
Inoltre abbiamo un sito in italiano meno aggiornato a dire il vero. In questo caso la guida utente é costituita da http://freedomotic.sednet.it/argomenti/guide/installazione/ e da http://freedomotic.sednet.it/argomenti/guide/utilizzo/ mentre quella di sviluppo da http://freedomotic.sednet.it/argomenti/guide/sviluppo/
Dal mio punto di vista sarebbe utile avere anche un manuale in pdf consultabile offline.
E' chiaro che mantenere entrambe le modalità richiede un certo impegno.
Non mi piacerebbe dover fare ogni volta un copia/incolla per generare una nuova versione.
Sto cercando un modo per automatizzare il processo partendo dalle pagine su wordpress e sul wiki di github. Qualche idea?
Ricapitolando: se avete suggerimenti su come organizzare i contenuti, cosa vorreste aggiungere e come ottimizzare le risorse aggiungete i vostri commenti.
Naturalmente ogni contributo (revisione, stesura di guide ecc.) è ben accetto.
Mauro
Giuseppe Pannullo
2016年6月2日 03:47:552016/6/2
收件人 Freedomotic - IoT and Smart Spaces Framework
Ciao Mauro ma x la documentazione perché non utilizzare https://readthedocs.org che si integra perfettamente con github? Non ne sono sicurissimo ma dovrebbe prevedere anche il multi language... Dentro i tuoi sorgenti aggiungi una dir d'oca e gestisci la documentazione sotto versionamento utilizzando o md o altra sintassi. Per molti progetti open è il punto di riferimento pratico e semplice da gestire e dovrebbe consentire anche la stampa.
Potremmo concentrare li tutte le guide e piccoli tooltips ed è tutto sotto controllo di configurazione
Fammi sapere che ne pensi
Potremmo concentrare li tutte le guide e piccoli tooltips ed è tutto sotto controllo di configurazione
Fammi sapere che ne pensi
Mauro Cicolella
2016年6月2日 10:10:562016/6/2
收件人 Freedomotic - IoT and Smart Spaces Framework
Ciao Giuseppe
la gestione della documentazione è un tassello di un più ampio refactoring che coinvolge anche il sito.
Questo è attualmente basato su drupal principalmente per il meccanismo con cui gestiamo l'installazione dei plugin e perchè in passato abbiamo utilizzato un forum poi abbandonato perché gli utenti ritenevano più pratica la mail che di fatto è sempre disponibile sugli smartphone.
Ad ogni modo sarebbe necessario un restyling del sito per renderlo più moderno.
Una possibile soluzione prevederebbe la presenza di pagine statiche su github per il sito istituzionale rimandando al wiki per la documentazione tecnica e per il manuale d'uso.
Eventualmente la componente drupal resterebbe in piedi solo per il marketplace finchè non troviamo un'alternativa che richiederebbe una riscrittura del codice legato alla gestione dei plugin (upload da parte degli sviluppatori e download da parte degli utenti con indicizzazione per categorie).
Il wiki e le pagine statiche potrebbero essere aggiornate via versioning con il contributo di altri utenti.
Il problema principale sembra essere l'impossibilità di generare della documentazione decente in pdf e in maniera automatica con tanto di indice e anche la possibilità di avere il multilanguage.
Stavo pensando anche all'adozione di https://github.com/jekyll/jekyll per gestire le pagine su github includendo anche il wiki.
ReadTheDocs sembra una buona soluzione anche se non mi piace molto il fatto che la documentazione sia ospitata su un altro server.
Intanto, consultando altri siti, ho trovato http://snipe.net/2015/07/sexy-documentation-from-markdown-with-couscous-and-tipue-on-github-pages/
Diciamo che l'argomento è abbastanza vasto e merita ulteriori approfondimenti.
Mauro
la gestione della documentazione è un tassello di un più ampio refactoring che coinvolge anche il sito.
Questo è attualmente basato su drupal principalmente per il meccanismo con cui gestiamo l'installazione dei plugin e perchè in passato abbiamo utilizzato un forum poi abbandonato perché gli utenti ritenevano più pratica la mail che di fatto è sempre disponibile sugli smartphone.
Ad ogni modo sarebbe necessario un restyling del sito per renderlo più moderno.
Una possibile soluzione prevederebbe la presenza di pagine statiche su github per il sito istituzionale rimandando al wiki per la documentazione tecnica e per il manuale d'uso.
Eventualmente la componente drupal resterebbe in piedi solo per il marketplace finchè non troviamo un'alternativa che richiederebbe una riscrittura del codice legato alla gestione dei plugin (upload da parte degli sviluppatori e download da parte degli utenti con indicizzazione per categorie).
Il wiki e le pagine statiche potrebbero essere aggiornate via versioning con il contributo di altri utenti.
Il problema principale sembra essere l'impossibilità di generare della documentazione decente in pdf e in maniera automatica con tanto di indice e anche la possibilità di avere il multilanguage.
Stavo pensando anche all'adozione di https://github.com/jekyll/jekyll per gestire le pagine su github includendo anche il wiki.
ReadTheDocs sembra una buona soluzione anche se non mi piace molto il fatto che la documentazione sia ospitata su un altro server.
Intanto, consultando altri siti, ho trovato http://snipe.net/2015/07/sexy-documentation-from-markdown-with-couscous-and-tipue-on-github-pages/
Diciamo che l'argomento è abbastanza vasto e merita ulteriori approfondimenti.
Mauro
Mauro Cicolella
2016年11月9日 04:45:152016/11/9
收件人 Freedomotic - IoT and Smart Spaces Framework
Ciao a tutti
finalmente è partito il piano di sviluppo di una documentazione adeguata.
Stiamo utilizzando Sphinx in coppia con ReadTheDocs in modo da poter generare un manuale in pdf consultabile offline e stampabile. Per ora stiamo lavorando alla versione inglese ma subito dopo passeremo a quella italiana e apriremo a contributi internazionali.
Si è deciso di separare il manuale utente da quello per gli sviluppatori in modo da non dover scaricare della roba che non ci serve realmente. Per ora stiamo lavorando al primo.
La beta è consultabile al link http://fd-user-manual.readthedocs.io/en/latest/ e il pdf scaricabile da http://readthedocs.org/projects/fd-user-manual/downloads/pdf/latest/
Ovviamente c'è ancora tanto da fare. Se volete contribuire alla revisione o alla stesura dei testi siete i benvenuti. Fateci sapere se vi piace o se aggiungereste/cambiereste qualcosa.
A presto
Mauro
Il giorno venerdì 27 maggio 2016 18:00:07 UTC+2, Mauro Cicolella ha scritto:
Mauro Cicolella
2016年12月3日 02:22:172016/12/3
收件人 Freedomotic - IoT and Smart Spaces Framework
I link ufficiali sono:
Il lavoro non è completo ma a buon punto.
Mauro
Il giorno venerdì 27 maggio 2016 18:00:07 UTC+2, Mauro Cicolella ha scritto:
回复全部
回复作者
转发
0 个新帖子