Ecrire une bonne doc

a marqué ce sujet comme résolu.

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 :

  • L'API Reference

Comment utiliser telle fonctionnalité ? Quelles constantes ? Quelles exceptions ? Quels fonctions ? Quels arguments ?

  • Les commentaires

Comment fonctionne ce morceau de code ? Que fait cette fonction ?

  • Les tutoriels

Comment utiliser mon programme ? Avec des exemples. Parce que c'est vachement indigeste de découvrir une bibliothèque à travers son API Reference.

  • La vision globale du code

Comment interagissent les modules ? Comment s'organisent les dossiers ? MVC est-il employé ? En gros, ce qu'il faut savoir si on souhaite contribuer.

Merci. =)

+1 -0

Oui, ce sont les points essentiels à considérer.

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.

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 else else { // state is unknown, throw an exception ou un default dans un switch.

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 surtout c'est là (cette classe, …) que je dois chercher. E.g. : pour écouter sur un port on instancie telle classe via tel factory, puis on lui attache le numéro de port de telle façon. Cf. les méthodes de la factory pour plus d'options.

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 ?

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.

+0 -0

Merci beaucoup pour ce message très constructif !

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 ici ?

+0 -0

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)

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…?)

Bref, pour des gros projets, il faudrait presque documenter la doc :) Ca peut prendre la forme d'un document de livraison, qui indique pour chaque livraison de logiciel quelles sont les docs à livrer avec.

+0 -0
Connectez-vous pour pouvoir poster un message.
Connexion

Pas encore membre ?

Créez un compte en une minute pour profiter pleinement de toutes les fonctionnalités de Zeste de Savoir. Ici, tout est gratuit et sans publicité.
Créer un compte