Derniers messages sur Zeste de Savoirhttps://zestedesavoir.com/forums/2015-02-08T14:26:38+01:00Les derniers messages parus sur le forum de Zeste de Savoir.Ecrire une bonne doc, message #428202015-02-08T14:26:38+01:00Looping/@Loopinghttps://zestedesavoir.com/forums/sujet/2331/ecrire-une-bonne-doc/?page=1#p42820<p>Et aussi, une bonne doc, il ne faut pas qu'on s'y perde dedans. Donc bien faire des docs différentes selon leur niveau: doc de spécifications, doc de conception préliminaire (archi, interfaces,…), doc de conception détaillée, Manuel utilisateur d'installation/exploitation…
Avec si possible une traçabilité entre les docs (genre telle fonctionalité dont on parle ici est documentée dans ce § de telle autre doc)</p>
<p>Il faut aussi penser à faire vivre cette doc. Lorsque tu as un truc à rajouter dans ton logiciel (nouvelle fonctionalité, correction…), il faut aussi penser aux impacts documentaires (est-ce que ça touche aux interfaces, ça rajoute un fichier de conf…?)</p>
<p>Bref, pour des gros projets, il faudrait presque documenter la doc <img alt=":)" src="/static/smileys/smile.png"> Ca peut prendre la forme d'un document de livraison, qui indique pour chaque livraison de logiciel quelles sont les docs à livrer avec.</p>Ecrire une bonne doc, message #428082015-02-08T12:39:22+01:00Vayel/@Vayelhttps://zestedesavoir.com/forums/sujet/2331/ecrire-une-bonne-doc/?page=1#p42808<p>Merci beaucoup pour ce message très constructif !</p>
<p>Au niveau de la dernière partie, serait-il intéressant de faire ça en expliquant aux autres comment écrire le programme, comme le suggère GuilOooo <a href="http://zestedesavoir.com/forums/sujet/1255/conception-dun-programme/?page=1#p21580">ici</a> ?</p>Ecrire une bonne doc, message #420642015-02-02T17:08:57+01:00Javier/@Javierhttps://zestedesavoir.com/forums/sujet/2331/ecrire-une-bonne-doc/?page=1#p42064<p>Oui, ce sont les points essentiels à considérer.</p>
<p>L'API référence peut-être générée automatiquement, dans ce cas n'oublie pas de commenter chaque méthode (en plus des paramètres d'entrée/sortie) en disant ce qu'elle fait dans la partie qui sert à générer la doc automatiquement.</p>
<p>Pour les commentaires dans le code, tu peux détailler les algorithmes que tu utilises, définir l'état attendu d'une variable, expliciter un <code>else</code> <code>else { // state is unknown, throw an exception</code> ou un <code>default</code> dans un <code>switch</code>.</p>
<p>Pour les tutoriels oui, ça peut être une doc fonctionnelle aussi. En partant de cas d'utilisation : je veux faire ci, c'est comme ça que je m'y prends et <strong>surtout</strong> c'est <em>là</em> (cette classe, …) que je dois chercher. E.g. : pour écouter sur un port on instancie telle classe via tel <code>factory</code>, puis on lui attache le numéro de port de telle façon. Cf. les méthodes de la <code>factory</code> pour plus d'options.</p>
<p>Je rajouterai la doc d'entrées/sortie du programme : quels fichiers en entrée, quels fichiers en sortie, où est-ce-qu'on va lire des données, où est-ce-qu'on les stocke, pourquoi comment, quel format attendu, qu'est-ce-qu'on peut paramétrer, où ? ça change quoi ?</p>
<p>Pour la dernière partie oui, c'est l'architecture générale de ton application. C'est un point essentiel et très souvent négligé quand "on a le nez dedans", on a toujours tendance à penser qu'on "fait du standard" mais ce n'est pas souvent le cas. D'abord en termes de localisation : Quel package/namespace correspond à quoi ? Où vais-je chercher les couches basses (DAO, …) où sont stockés les éléments d'interface ?
Ensuite en terme d'architecture à proprement parler : "tous les éléments d'interface sont observés par XXX, voici la liste des évènements qu'il peut lancer et ce à quoi ils correspondent", "tel type n'est qu'une façade pour tel autre", … On doit donc à la fois y retrouver ton organisation de modules effectivement et les emplacements associés, mais également certains patterns connus quand ils sont utilisés.</p>Ecrire une bonne doc, message #417482015-01-30T20:56:07+01:00Vayel/@Vayelhttps://zestedesavoir.com/forums/sujet/2331/ecrire-une-bonne-doc/?page=1#p41748<p>La documentation dans un projet informatique c'est quand même fichtrement important. Ne serait-ce que pour s'y retrouver soi-même plus tard. Je me demandais donc s'il existait une méthode idéale (théoriquement, sans prendre en compte les contraintes temporelles, humaines…) pour écrire une bonne doc. Ayant un peu réfléchi à la question, mais ne possédant que très peu d'expérience en la matière, il me semble y avoir quatre points à considérer :</p>
<ul>
<li>L'API Reference</li>
</ul>
<p>Comment utiliser telle fonctionnalité ? Quelles constantes ? Quelles exceptions ? Quels fonctions ? Quels arguments ?</p>
<ul>
<li>Les commentaires</li>
</ul>
<p>Comment fonctionne ce morceau de code ? Que fait cette fonction ?</p>
<ul>
<li>Les tutoriels </li>
</ul>
<p>Comment utiliser mon programme ? Avec des exemples. Parce que c'est vachement indigeste de découvrir une bibliothèque à travers son API Reference.</p>
<ul>
<li>La vision globale du code</li>
</ul>
<p>Comment interagissent les modules ? Comment s'organisent les dossiers ? MVC est-il employé ? En gros, ce qu'il faut savoir si on souhaite contribuer.</p>
<p>Merci. =)</p>