[openplacos-dev] Site web du projet

[miaouf kirsh <miaoufkirsh@xxxxxxxxx>]

Salut à tous,

Il ne vous a surement pas échappé que notre site openplacos.tuxfamily.org n'est pas très a jour \ maintenu depuis quelques temps (presque 1 ans en fait).
Je dirais même c'est un gros bordel, on a du mal a s'y retrouver.
Même si on s'est bien amusé a monter le truc, mon avis est que l'on a été trop ambitieux en voulant monter un site/wiki/blog/forum/bugtracker et que cela a aboutit a un truc trop chronophage pour être maintenu correctement.

De plus, on utilise a présent le repo git lui même pour écrire la documentation, via des fichier ".md" et la syntaxe markdown :
quelques exemples :

• https://github.com/openplacos/openplacos/blob/unstable/programmer_guide.md
  
• https://github.com/openplacos/openplacos/blob/unstable/utils/arduino_firmware/README.md
• etc
  

Personnellement, je trouve ça beaucoup plus pratique a écrire, ca encourage également a rédiger la doc en // du codage.
Ca permet également d’être plus flexible tout en pérennisant la doc.
Cette pratique est monnaie courante pour les projets ruby hébergés sur github, et on se prend facilement au jeu.
(la plupart du temps je lit uniquement la doc disponible dans les repos, elle est généralement plus fraiche, et ca donne également une bonne idée de la qualité du projet : doc a jour par rapport au dernier commit etc ...)
Le revers de la médaille, c'est une désynchronisation inévitable avec le site web, et la fragmentation de la doc qui se retrouve dispatchée a droite a gauche dans le repo ( le principal inconvénient du markdown c'est qu'on ne peut pas faire pointer de liens vers un autre document markdown en mode wiki).
Mais la également il y a plein de solutions (plus ou moins pratiques) pour palier a ces problèmes. 
par exemple le wiki de github est un repos git qui prend en entré des fichiers markdown, ou encore, il existe plein d'outils pour transformer le markdown en html/pdf/whatever ou générer un site web statique.

Partant de la, je pense il y a deux points a discuter :

1. Que souhaite ton faire avec le site web, ou en d'autre mots, quels sont les services qu'il doit rendre.
2. Comment gere t'on le rendu de la documentation (wiki synchronisé avec le repo ? site généré a partir de la doc du repo ? etc )

Voila

------------ Avis du Kirsh -----

je donne mon avis en même temps :

1 : Pour le site web, il fraudais un truc plus minimaliste, qui presente le projet en quelques lignes (contrairement au site actuelle ou il faut se tapper 30 paragraphes avant de comprendre a quoi ca sert), avec quelques screenshots, les principales features, un flux de news et des liens qui pointes vers les infos principales ( code / documentation /ML ). J'ai callé en fin de mail des liens vers les sites de gros projet qui reprennent un peut ce concept (site minimaliste et renvois vers la doc, par exemple hebergé sur github ou générée a partir du repo).
A mon sens le forum n'est pas necessaire (il faut atteindre une masse beaucoup plus importante d'utilisateur).
La gestion des bug est délégué a github

2 : On pourrais se palucher un petit script (si ca existe pas deja) qui parcours le repo pour sélectionner les fichiers markdown et les balancer dans un générateur de site statique tel que jekill.
à chaque sortie de version, on lance le script, on génère le site et on le traque dans un repo git, avec un tag pour le même numéro de version.
çà devrai permettre de rester synchronisé et en plus de pouvoir accéder a la doc spécifique de chaque version (comme on a l'habitude de tout changer entre chaque version, ca peut etre pas mal)

http://www.sinatrarb.com/
http://jekyllrb.com/
http://www.gitlabhq.com/
http://gembundler.com/