Discussion :

[Neckara]

Pour le quick start, je peux donc juste leur dire dans un README :
- lancez cmake : cmake . -G "Unix Makefiles" && make
- pour plus d'info générez la doc ;
- ou allez voir notre site, etc...

Et tu n'as pas l'impression que cela fait un peu double emploi avec les sources doxygen

Ben non.

Utilises tes fichiers markdown (ou du moins leur contenu) pour créer ton wiki si tu le souhaites, mais il ne sert à rien (il est même particulièrement dangereux) d'essayer de couvrir tout l'éventail des outils qui sont susceptibles de générer ta documentation : Dans le meilleur des cas, cela provoquera une duplication particulièrement dangereuse de tes informations

Je n'ai jamais dit que je voulais faire un wiki
Dans le README, je donne les info de base ;
Dans CHANGELOGS, je met les modifications ;
Dans INSTALL, je dis comment compiler ;
Dans CONTACT, je dis comment nous contacter ;
Dans LICENCE, je donne la licence.
Ce sont en somme des informations de base non?

Cette information t'intéresse peut être, mais elle n'intéresse très certainement pas celui qui veut compiler ton projet!

Au contraire, il sait ce qui a changé et les futures features à venir.

Si il veut savoir "ce qu'il reste à faire", il se foutra pas mal de savoir "depuis quand c'est sur la pile" ni "ce qui a été fait entre temps".

Ben il regarde juste la dernière journée écrite.

De la même manière, tu te rendras rapidement compte que tu n'as absolument pas besoin de savoir dans un même temps ce qui a été fait et ce qu'il reste à faire!

Soit, tu voudras te "remonter le moral" en pouvant te faire une idée du chemin parcouru, soit tu voudras savoir ce qu'il te reste à faire, histoire d'attaquer une des étapes.

Personnellement, pour le moment, je fais les deux en même temps.
J'ouvre le fichier CHANGELOGS et à chaque modifications/chaque chose faite, j'édite le CHANGELOGS en retirant l'entrée des choses à faire et je rajoute peut être une entrée dans le changelog.

[koala01]

Pour le quick start, je peux donc juste leur dire dans un README :
- lancez cmake : cmake . -G "Unix Makefiles" && make
- pour plus d'info générez la doc ;
- ou allez voir notre site, etc...

En gros, c'est l'idée

Ben non.

Et pourtant, si, à partir du moment où il est tout à fait possible de générer des pages quasiment similaire avec doxygen qu'avec le format markdown

Je n'ai jamais dit que je voulais faire un wiki

Je sais bien, je te donnais un exemple concret d'utilisation du format markdown, rien de plus

Dans le README, je donne les info de base ;
Dans CHANGELOGS, je met les modifications ;
Dans INSTALL, je dis comment compiler ;
Dans CONTACT, je dis comment nous contacter ;
Dans LICENCE, je donne la licence.
Ce sont en somme des informations de base non?

Tout à fait.

Mais tu ne crois pas qu'un fichier de texte brut est tout aussi efficace et lisible

Au contraire, il sait ce qui a changé et les futures features à venir.

Si il s'intéresse à ce qui a changé, il ne s'intéresse pas forcément aux features à venir et, si il veut savoir ce que tu lui réserve pour la suite, il se fout pas mal de ce qui a déjà été fait

Personnellement, pour le moment, je fais les deux en même temps.
J'ouvre le fichier CHANGELOGS et à chaque modifications/chaque chose faite, j'édite le CHANGELOGS en retirant l'entrée des choses à faire et je rajoute peut être une entrée dans le changelog.

Tu te casses la tête pour rien!

Tu sais, personnellement, je m'en fous royalement que tu fasses à ta guise!

Mais ce que je trouve dommage, c'est que tu perdes ton temps à envisager une utilité qui est très loin d'être prouvée à une pratique inhabituelle, alors que tu as à ta disposition une vaste gamme de projet d'envergure pour te servir d'exemple et que -- à tord ou à raison -- tous ces projets vont au plus simple en ce qui concerne les changelog.

La plupart n'exposent d'ailleurs pas leur todo-list ailleurs qu'au niveau du "request tracker" (la partie du bugtracker qui permet de demander de nouvelles features )

Prend exemple sur l'existant, tu verras que le format utilisé est parfaitement adpaté au texte brut et qu'il permet même à certains outils (surtout sous linux ) d'en avoir une vision parfaitement user friendly.

Si l'on prend l'exemple de la plupart des projet GNU, le format du changelog est proche de

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
YYYY-MM-DD nom prenom <e-mail>
     * modification 1
     * modification 2
     * ...
     * modification N

Les premieres lignes du fichier étant les dernières modifications en date.

Simple et efficace! Et parfaitement lisible par l'humain en utilisant un simple éditeur de texte!

Pourquoi ne pas simplement décider de faire comme eux, au lieu de prendre le risque de te fourvoyer à vouloir mettre ton propre format au point

D'autant plus que, comme je te l'ai dit plus tot, tu trouveras sans doute motivant le fait de voir d'où tu viens et où tu vas dans un premier temps, mais l'effet sera très certainement inversé d'ici peu, quand tu commenceras à avoir beaucoup plus de choses "dans le pipe" que de choses résolues

[Neckara]

Merci pour tes réponses.

Pour le moment, je vais rester avec mes fichiers *.md et un README "minimal".

Si cela pose vraiment problème, j'aviserais mais je ne pense pas non plus que ce soit le plus important dans le dépôt (qui n'a pas encore toutes les sources ).

Je passe donc le sujet en résolu et je me remet au boulot