Consultez la FAQ sur le ZF avant de poster une question
Vous n'êtes pas identifié.
Salut etaty,
à mon sens ce n'est pas suffisant, parce la doc d'un framework doit être structurée, et permettre de trouver rapidement et clairement l'aide nécessaire à l'emploi d'une partie très précise du framework. Bien que les commentaires me semblent très importants, ils ne devraient que compléter une doc de référence déjà exhaustive au maximum.
Mais je détaillerai tout ça très prochainement
Hors ligne
Ca sent la surprise
Hors ligne
je ne sais pas s'il y aura tant de surprise que ça
simplement tous les détails de cette idée de documentation alternative pour le ZF (ce qu'elle doit contenir, comment le contenu sera géré, les commentaires, le rapport avec la doc officiel, etc...)
Je vais essayer de faire vite...
Hors ligne
Belle série de contributions !
Quelques réflexions :
Il doit y avoir, a mon avis deux approches pour une "bonne" documentation sur une chose aussi vaste et complexe qu'un framework.
-- Une première approche de type linéaire à complexité croissante, dans le style "Apprendre le ZF en 24 heures".
Donc la construction d'une application qui regroupe un grand nombre de concepts et que l'on fait réaliser en pas à pas au lecteur.
Exemple d'une application de gestion de médiathèque, et à la fin du bouquin on se trouve avec un appli web qui utilise une base de données, l'identification, les droits, les RSS pour être au courant des nouveaux volumes, la recherche, l'autocomplétion avec Dojo etc...
-- Une deuxième approche est une documentation de référence qui permet à un développeur de trouver LA bonne technique à utiliser et COMMENT l'utiliser grâce à un exemple complet (directement fonctionnel : implantation des méthodes) alors qu'il est en cours de réalisation d'une application dans le cadre de son activité professionnelle.
Une référence facile à consulter ou par exemple on trouve les règles de surcharge sans être obligé d'aller dans le source du Zend Framework.
A mon avis les deux approches sont complémentaires. La première approche est la plus difficile à garder à jour. Mais elle est l'entrée obligatoire pour ceux qui découvrent le ZF ou carrément ne connaissent aucun framework...
La documentation actuelle ne doit pas être occultée, mais doit servir à être exhaustif sur les fonctionnalités à décrire.
Je pense que tous les développeurs qui ont une dead line en tant que salarié ou libéral (ou comme c'est mon cas qui porte les deux casquettes) comprendront l'importance d'une vraie doc de référence.
Je suis prêt à apporter mon aide même si je suis loin d'avoir la compétence de la plupart des contributeurs de ce thread.
Je peux en revanche être utile dans le cadre de la relecture et la critique, bienveillante, de la documentation produite en faisant profiter de mon expérience en la matière en tant qu'écumeur d'ouvrages techniques et de documentations depuis mon adolescence, soit depuis environ 35 ans.
Voilà, à condition d'avoir un comité de pilotage qui assure un produit cohérent et fiable, et si chacun apporte son aide, je pense que l'on peut aboutir à quelque chose de vraiment utile à la communauté.
Dernière modification par Jean-Marc Rigade (18-10-2008 05:54:35)
Hors ligne
Je suis assez d'accord sur les approches que donne Jean-Marc.
L'essentiel c'est de concevoir ou d'utiliser un outil qui permette de maintenir cette doc sans que ce soit pénible.
Par mon expérience, pas sur zend, mais globale, je suis plutôt pour une documentation structurée, avec des exemples avancés, qu'une brochette d'entre nous pourront se permettre de pondre.
Mais une doc sans commentaires des internautes.
Et à côté de ça, je suis persuadé que la meilleure solution reste le wiki. C'est un très bon moyen de regrouper des tonnes de ressources et de les entrecroiser facilement. Donc des contributions apportées par qui veut bien, et qui seront vérifiées par les plus pro.
Après, on ne voit ça que très rarement, que ce soit dans les tuto ou les docs, je suis très friand des exercices qui servent d'exemples avancés et qui permettent aux développeurs débutants de 'réfléchir'. Avec bien sûr la solution, mais c'est en partant du principe que ceux qui le souhaitent peuvent jouer le jeu.
Je trouve qu'on apprend surtout de ses erreurs, et quand on compare sa réalisation avec "la" bonne solution. Après tout est relatif, c'est sujet à discussion comme toujours, mais on peut quand même se mettre d'accords sur "la" bonne pratique du framework.
Mis à part ça, je pense qu'on devrait déplacer toutes ces suggestions dans un autre thread, parce qu'on s'écarte largement de la question de notre pauvre 'miboo'
A+ benjamin.
Hors ligne
miboo a écrit:
Ça m'intéresserait si tu avais un exemple de ce que tu dis ?
Je te renvoie au blog de Sara Golemon, par exemple
http://blog.libssh2.org/index.php?/arch … tring.html
Hors ligne
Julien a écrit:
miboo a écrit:
Ça m'intéresserait si tu avais un exemple de ce que tu dis ?
Je te renvoie au blog de Sara Golemon, par exemple
http://blog.libssh2.org/index.php?/arch … tring.html
Merci, je vais voir ça
Pour ceux qui sont intéressés par le projet de doc alternative, un topic a été créé à cette adresse :
http://www.z-f.fr/forum/viewtopic.php?id=1992
Dernière modification par miboo (18-10-2008 23:25:55)
Hors ligne
Concernant l'idée que j'avais derrière la tête au sujet de la création d'une documentation alternative, c'est posté sur :
http://www.z-f.fr/forum/viewtopic.php?pid=11304
J'attends vos commentaires, et bien sûr votre participation prochaine
Hors ligne