Forum d'entraide PHPFrance

Bonjour,

je me lance dans la dernière partie de mon projet, à savoir écrire la documentation. Mais je me pose pas mal de questions. Comment écrire la documentation ?

Oui, je connais évidement les commentaires dans les sources, mais ce n'est pas suffisant quant à l'utilisation d'une classe. On peut donner des indications, renseigner, mais quelle documentation attend ton pour un framework ?

Je fais une différence entre documentation (qui serait la documentation des classes et méthodes), et guide utilisateur (qui apprendrait à manipuler les librairies). Que dois-je choisir ou privilégier ? Qu'est-ce qui vous conviendrait le plus ? Et que doit-on le plus mettre en avant ?

Voilà, merci pour vos indications .

Si ton projet a vocation à être disponible pour tous publics (quelle que soit sa licence), un guide utilisateur serait plus approprié. Et si tu veux rédiger ce guide pas à pas, un wiki peut très bien faire l'affaire ; pour cela, regarde du côté de WikiNi ou de DokuWiki.

Pour illustrer mon propos, jette un coup d'œil à la documentation de DotClear et inspire-t'en.

Je n'aime pas la documentation de DotClear (DC) . Ça se présente comme une documentation orientée programmeur, mais ils ne vont pas assez loin. J'ai du à plusieurs reprises travailler sur DC (pour des créations de plugins), et je finis fâché avec DC.

Merci pour les *wikis. Je vais jeter un oeil là-dessus .

Je plussoye l'idée du wiki, c'est un outil tout à fait adapté pour le job (quel que soit le public cible de la documentation que tu vas rédiger).

Sinon, peut-être que ce que tu veux faire ressemble au guide utilisateur de Symfony, un autre framework ( http://www.symfony-project.com/book/1_0/ ). Tu peux aller le voir et t'en inspirer. Cependant cette documentation n'est pas ce qu'il y a de plus pratique à consulter pour un utilisateur comme pour un développeur, je te conseille d'éviter de la cloner, elle est perfectible

NB : certains chapitres sont traduits en français, mais pas tous.

Celle de Symfony n'est pas très clair. En revanche, j'adore cette de ZF, nan ?

Personnellement, je ne connais pas celle de Symphony, en revanche, je commence à connaître une bonne partie de celle du Zend Framework et je lui accorde (à priori) une nette préférence y compris à une doc PHPDoc.

L'idée du Wiki n'est pas mauvaise non plus, mais je crois qu'il faudrait distinguer deux types de documentations :
- Celle pour le développeur du projet, auquel cas PHPDoc pourrait parfaitement être appropriée, pour autant qu'elle soit complète. Ceci dit, en s'y appliquant avec phpDocumentor, on pourrait créer une documentation extrêmement complète;
- Le Wiki ou une forme similaire pour l'utilisateur, développeur utilisant le projet pour développer le sien et donc expliquant comment se servir de quoi et pourquoi, ce qu'on ne voit pratiquement jamais une documentation PHPDoc sauf peut-être celle de phpDocumentor lui-même....

J'ajouterais qu'arriver à faire comprendre le fonctionnement de l'application à l'utilisateur est une tâche ardue. Je suis par exemple convaincu que beaucoup d'utilisateurs du ZF vont construire des petites usines à gaz avec du code redondant alors que quelques lignes suffiraient pour utiliser ce qui est déjà inclus dans le ZF mais pour lequel on ne trouve d'explication nulle part, et pourtant, il y a pas mal d'idées de génie dans ce framework. Donc la doc doit être illustrée d'exemples clairs et eux-même documentés.

Enfin bon, ce n'est qu'un avis hein ?

Merci Cyrano.

Si on résume donc : une documentation PhpDoc (va falloir que j'apprenne à m'en servir de ce truc), un guide utilisateur et programmeur très complet, et des tonnes d'exemples pour bien illustrer le guide.

Je pars sur cette idée. Le fait d'utiliser un wiki me semble une bonne idée. Ça renforce l'idée de communauté après tout. Il faut voir si on peut bien l'intégrer dans un site, et s'ils sont bien accessibles.

Un truc à savoir à propos de phpDocumentor : on peut générer deux types de documentations :
- une doc utilisateur;
- une doc complète pour le développeur.

Dans la première, on peut en effet n'afficher que ce qui est "public" et donc l'utilisateur n'a pas à trier entre les méthodes "public", "protected" ou "private" pour savoir de quoi il peut se servir puisqu'on peut ne lui afficher que les méthodes "public"

Dans la seconde au contraire, on mettra tout précisément parce qu'on en a besoin pour continuer le développement de l'application en utilisant ce qui est déjà en place.

Oh ! Ah en effet c'est plutôt intéressant. Je vais approfondir PhpDoc alors. Ça me semble plutôt intéressant.

Merci .

Le fait d'utiliser un wiki me semble une bonne idée. Ça renforce l'idée de communauté après tout. Il faut voir si on peut bien l'intégrer dans un site, et s'ils sont bien accessibles.

Je n'ai pas essayé à fond les wikis dont j'ai parlé, mais tu as la possibilité de créer tes propres templates, auquel cas tu as toutes les cartes en main. Mais, à la base, ils ne sont a priori pas difficiles sur ce point.