Que voulez-vous pour la doc ?

[Laurent Jouanneau]

Bonjour,

Encore une fois, j'ai pris le problème à l'envers : j'ai foncé tête
baissée dans le développement, sans demander ce que vous voudriez :-)

Donc on recommence : qu'aimeriez vous que l'on fasse pour la doc ?
(doc = manuel et plus tard, les tuto, cookbook etc.. pas la doc de
l'api, c'est autre chose)

Pour ma part je pense qu'il est primordiale :

- de mettre la doc sur un dépôt (github), pour permettre les modifs
profondes, offline et de permettre de propager des modifs dans les
différentes versions (par merge ou cherry-pick)
- de pouvoir générer la doc en PDF
- de faciliter les contributions des développeurs peu expérimentés
(donc sans passer par git, et pour ça, un wiki comme dokuwiki était
pas mal je pense)

Et vous, comment voyez vous tout ça ? quelle solution technique
envisageriez vous ? Quelle est votre syntaxe wiki préférée ?

Et ce serait sympa d'avoir les réponses d'un max de personnes ;-)

Laurent

[FoxMaSk]

Bonsoir,

Le 30 mars 2012 17:46, Laurent Jouanneau <ljoua...@gmail.com> a écrit :

Bonjour,

Encore une fois, j'ai pris le problème à l'envers : j'ai foncé tête
baissée dans le développement, sans demander ce que vous voudriez :-)

Des fois ; si on ne prend pas le taureau par les cornes et que personne ne se manifeste ou est intéressé  ; il faut bien se lancer ;)

Donc on recommence : qu'aimeriez vous que l'on fasse pour la doc ?
(doc = manuel et plus tard, les tuto, cookbook etc.. pas la doc de
l'api, c'est autre chose)

J'aimerai un truc comme ceci http://www.codecademy.com/#!/exercises/0
Mais ca demande du boulot ;) et ca irait dans les tuto donc plus tard

Pour ma part je pense qu'il est primordiale :

- de mettre la doc sur un dépôt (github), pour permettre les modifs
profondes, offline et  de permettre de propager des modifs dans les
différentes versions (par merge ou cherry-pick)

je suis partagé entre l'intérêt du versionning apporté par github (mais la difficulté de trouver une solution qui exploite github qui remplisse les prérequis ci dessous), et des solutions existantes (ou non) qui, de facto "versionnent" (historisent) les modifications des pages.

- de pouvoir générer la doc en PDF

+1

- de faciliter les contributions des développeurs peu expérimentés
(donc sans passer par git, et pour ça, un wiki comme dokuwiki était
pas mal je pense)

+1

Et vous, comment voyez vous tout ça ? quelle solution technique
envisageriez vous ?

pour le moment je n'en vois pas ; je creuse encore.

Quelle est votre syntaxe wiki préférée ?

Pour moi c'est accessoire ; si le système est bien foutu ; on prend la syntaxe comme elle est je pense.
Comme il y a (souvent) une barre d'outil pour la mise en forme ben c'est accessoire.

Et ce serait sympa d'avoir les réponses d'un max de personnes ;-)

Laurent

au suivant ;)

[Lepeltier kévin]

On Fri, 30 Mar 2012 17:46:25 +0200, Laurent Jouanneau
<ljoua...@gmail.com> wrote:
> Bonjour,
>
> Encore une fois, j'ai pris le problème à l'envers : j'ai foncé tête
> baissée dans le développement, sans demander ce que vous voudriez :-)
>
> Donc on recommence : qu'aimeriez vous que l'on fasse pour la doc ?
> (doc = manuel et plus tard, les tuto, cookbook etc.. pas la doc de
> l'api, c'est autre chose)
>
> Pour ma part je pense qu'il est primordiale :
>
> - de mettre la doc sur un dépôt (github), pour permettre les modifs
> profondes, offline et de permettre de propager des modifs dans les
> différentes versions (par merge ou cherry-pick)

J'aime bien l'idée de github pour la doc, ça m'intrigue.

> - de pouvoir générer la doc en PDF

J'en vois pas l’intérêt, mais je suppose que c'est utile pour certain

> - de faciliter les contributions des développeurs peu expérimentés
> (donc sans passer par git, et pour ça, un wiki comme dokuwiki était
> pas mal je pense)

L'idée d'avoir un wiki synchro avec git est bonne idée, excellente
même, c'est le meilleur des deux mondes.
Mais il ne faut pas abandonner l'édition en ligne en wiki, c'est ce qui
amène le plus de contribution.

> Et vous, comment voyez vous tout ça ? quelle solution technique
> envisageriez vous ? Quelle est votre syntaxe wiki préférée ?

Un wiki (n'importe lequel), qui en plus fait des commit et push sur
github à chaque maj.
C'est l'idée non ?

Sinon pour la syntaxe wiki, le textile est génial, très léger, très
lisible et assez intuitif.

> Et ce serait sympa d'avoir les réponses d'un max de personnes ;-)
>
> Laurent

--
kévin

[Laurent Jouanneau]

Le 30/03/2012 21:46, Lepeltier kévin a écrit :
> On Fri, 30 Mar 2012 17:46:25 +0200, Laurent Jouanneau

>> - de pouvoir générer la doc en PDF
>
> J'en vois pas l’intérêt, mais je suppose que c'est utile pour certain

Principalement pour la consultation offline et pour ceux qui veulent
imprimer. Et c'est utile car j'ai eu pas mal de retour là dessus depuis
le début.

Et le pdf est le troisième fichier le plus téléchargé après le framework
sur download.jelix.org. Donc je pense que c'est utile à beaucoup ;-)

Laurent

[Vincentv]

La syntaxe Markdown a un certain succés avec pygments pour la coloration syntaxique.

Github utilise gollum (https://github.com/github/gollum ) pour les wiki. 

mais c'est en ruby et il faut y connecter un système d'authentification ^^

Pour les tutos, il y a aussi rails for zombies (http://railsforzombies.org/) qui propose un truc sympa. mais faut le temps ^^

Pour manipuler un depot git, il y a une extension php libgit2/php-git (https://github.com/libgit2/php-git)

Pour en revenir à l'authentification un service oauth pourrait être pratique pour les différents site :)

[Florian Lonqueu-Brochard]

> de mettre la doc sur un dépôt (github), pour permettre les modifs profondes, offline et  de permettre de propager des modifs dans les différentes versions (par merge ou cherry-pick)

Nickel, ça permettra de pouvoir modifier offline et ça c'est cool.

> de pouvoir générer la doc en PDF

J'en ai pas personnellement l'utilité, mais je comprend que pas mal de monde le souhaite.

> de faciliter les contributions des développeurs peu expérimentés (donc sans passer par git, et pour ça, un wiki comme dokuwiki était pas mal je pense)

Je trouve pas ça forcément vital, je trouve l’éditeur de wiki sur github très bien (history, comparaison de révisions, etc).

[Laurent]

Le 31/03/2012 18:36, Vincentv a écrit :
> Pour manipuler un depot git, il y a une extension php libgit2/php-git
> (https://github.com/libgit2/php-git)

Pour mon gitiwiki, j'ai préféré utiliser glip
https://github.com/patrikf/glip même si sa maintenance est quelque peu
abandonnée (mais il y a des forks plus actifs )

Laurent

[Contact Pandela]

Bonjour,

Pour moi, le système d'édition en ligne est un plus niveau
accessibilité, je ne suis pas encore un grand fan de l'utilisation de
Git, alors que là, ça permet à n'importe qui de modifier la doc
online, facilement.

Il faut garder la doc en PDF, très utile.

La syntaxe wiki, peu importe, elles sont toute assez accessible, la
syntaxe Markdown à l'air d'avoir le vent en poupe.

Sinon je peux volontier donné une aide pour la communauté, durant le
peu de temps libre qu'il me reste.

Le 30 mars 2012 17:46, Laurent Jouanneau <ljoua...@gmail.com> a écrit :

[Lepeltier kévin]

Je propose d'abandonner la symtaxe wiki, et d'écrire toute la doc en
YAML ...

--
kévin

[FoxMaSk]

Si tu ponds le parser wikirender dokuwiki2yalm ;-)

[Florian Lonqueu-Brochard]

Ce troll xD

[Lepeltier kévin]

:)
--
kévin

--
--
kévin

[Lepeltier kévin]

Je viens de regarder Markdown
http://daringfireball.net/projects/markdown/syntax#philosophy
et c'est vrais que c'est sympa, personnellement je préfère quand même
textile, pour des détails.
http://textile.thresholdstate.com/
Ils sont très proche l'une de l'autre, l'un à sûrement pompé sur
l'autre d'ailleurs.

--
kévin

On Mon, 2 Apr 2012 16:59:25 +0200, Contact Pandela <con...@pandela.ch>
wrote:

[Contact Pandela]

Ou alors la syntaxe wiki de wikimedia ou alors pk pas en pur html...ou
un wysiwyg?