Discussion :

[goomazio]

Bonjour,

Quel support utilisez-vous pour la documentation d'une application, documentation aussi bien technique pour les développeurs que "logicielle" qui "explique comment le logiciel fonctionne, et/ou comment on doit l'employer" ?

Quand on débute dans une nouvelle entreprise, il faut assimiler beaucoup d'informations : des procédures, méthodes, trucs et astuces, ... La structure du serveur de fichier, du dossier des sources, du projet, des bibliothèques de code... On peut alors penser à créer une base de connaissance qui permettra aux futures nouveaux de s'en sortir plus facilement. Ca, c'est pour les développeurs mais la documentation logicielle est tout aussi importante pour les utilisateurs.

Peut importe pour qui on souhaite la créer, la documentation, comme les commentaires dans le code, doit être à jour et non superflue. Le nouveau dév. ou utilisateur peut vite penser à jeter ses notes à la poubelle, ou à abandonner la mise à jour du *support plus évolué au choix* s'il est allé jusque là dans la centralisation des informations importantes, dès qu'il se rend compte que c'est devenu inutile, parce que lui ou le dernier à avoir rejoint l'équipe connait tout par cœur et/ou parce que c'est devenu un bazar monstre etc.

Tout dépend du contexte, de la complexité du truc à documenter, du nombre de personne qui doivent se documenter, ... Parfois c'est inévitable, parfois c'est superflu, ça peut être une perte de temps comme l'inverse.


Alors, combien de fois avez-vous vu des "documentations" pourrirent dans un coin ? Si vous avez profité de documentations utiles (mise à part celle du framework qu'on utilise, qui est souvent proche de la perfection), comment étaient-elles structurées et comment leur mise à jour étaient-elles gérées ? Sur quel support ? Pour quelle audience ? Ma question concerne plutôt un contexte où la doc ne se justifie pas totalement : informatique de gestion, 10 développeurs, la formation à l'installation suffit... mais pas assez que pour se passer d'un helpdesk (qui ne fait pas que de la réception de rapport de bug mais aussi de la formation). Dans ce contexte, la maintenabilité du code pourrait aussi y gagner avec une documentation technique.


Il y a sur Developpez beaucoup de débats sur les commentaires dans le code, la réussite des projets, l'aide aux nouveaux développeurs, etc. qui évoquent souvent la documentation mais je n'ai rien trouvé de spécifique.

Merci d'avance pour vos retours d'expérience.

[shadowmoon]

Bonjour,

J'ai souvent travaillé dans des grands groupes, et, à chaque fois, j'arrive à obtenir un modèle de document à remplir, ou alors je me base sur les documents déjà existants.

De plus 2 versions sont souvent en cours, une pour les utilisateurs finaux, et une plus technique pour les autres membres de l'équipe et les administrateurs chez le client.

Toutes les deux suivent le même schéma

1) une présentation générale de l'application : à quoi elle sert, qui peut l'utiliser, comment ...

2) la liste de toutes les fonctionnalités, avec un descriptif et leurs accès dans les menus

3) les éventuelles évolutions si une nouvelle version est prévue

Dans le doucement "technique", le niveau de détails est beaucoup plus avancé pour les points 2) Et 3)

[Invité]

J'ai fait pas mal de documentations techniques à mes début, que ce soit pour des clients ou en interne.
Je glisse régulièrement des vannes dans mes documents.
Jamais personne ne m'en jamais parlé.
Conclusion : tout le monde réclame de la documentation mais personne ne la lit.

[Zirak]

Conclusion : tout le monde réclame de la documentation mais personne ne la lit.

Amen...

C'est un peu la sensation que j'ai aussi, j'ai souvent l'impression d'y passer du temps "pour rien"...

[goomazio]

Le modèle de document semble être une très bonne idée : pas de "style" différent qui mène à une documentation hétérogène, avec certaines parties très bien construites et d'autres très mal.


Personne ne l'a lit. Les gens peuvent préférer poser des questions aux collègues que de lire la documentation. Ce qui est même plutôt bien, ça permet de parler aux collègues. La doc serait un outil de dernier recours, au cas où les collègues n'ont pas de réponse. La doc permettrait aussi de se débrouiller quand on est seul (comme par exemple les procédures de gestion d'incident qui servent entre autre à pouvoir gérer un incident quand le responsable principal n'est pas là).

Comme contre exemple, je pense aux notes personnelles qu'on a tous : le raccourcis sur le bureau vers le document scanné du menu de la cantine, des briques de code (scripts SQL, ...), la procédure pour créer, produire et livrer une commande (ça c'est pour les utilisateurs).

Comme pour les commentaires dans le code, un point important serait donc de se limiter à l'essentiel :
- une version complète pour ceux qui veulent se former seul (pour lire de la doc le soir avant de dormir)
- une version résumée où on ne retrouve que l'essentiel, une FAQ

Un autre point qui va de pair avec ça est la clarté ou la structure de la doc.


On peut se demander si la doc n'est pas un sujet important à notre époque : il y a un gros turnover, les gens ne sont plus spécialisés mais touchent à tout, certaines choses sont mises à la disposition d'un très grand nombre de personnes (qu'il faut donc éventuellement former)... On s'éloigne peut être du système du forgeron qui forme son apprenti et qui partage son savoir par voie orale (ou c'est moi qui m'éloigne ).

[shadowmoon]

Conclusion : tout le monde réclame de la documentation mais personne ne la lit.

Amen...

C'est un peu la sensation que j'ai aussi, j'ai souvent l'impression d'y passer du temps "pour rien"...

Moi j'ai connu des cas ou ce n'était pas "pour rien", notamment la documentation pour l'installation, surtout quand ça se passe comme ça (ou variantes) :

Personne X :" Je viens d'installer ton logiciel truc. Ça marches pas, ça ne veut pas se lancer !!!"

Moi : "Tu as bien vérifié les prérequis et suivi la procédure mentionnés dans le document d'installation ?"

Personne X :" Non quelle doc, j'ai jamais rien eu, j'ai du me débrouiller avec le setup !"

Moi : "Ah bon ? Pourtant je te l'ai envoyé par mail le date à heure et tu peux aussi le consulter sur le réseau à adresse"

Personne X : "Euh ... ben ... euh ... bon, je vais voir ça ..."

[Invité]

Moi j'ai connu des cas ou ce n'était pas "pour rien", notamment la documentation pour l'installation, surtout quand ça se passe comme ça (ou variantes)

Déjà eu ça aussi :
X: La méthode de ton document marche pas !
Moi : Ouvre le fichier, on va le faire ensemble.
X : On le trouve où, ton document ?

[Glutinus]

J'ai fait pas mal de documentations techniques à mes début, que ce soit pour des clients ou en interne.
Je glisse régulièrement des vannes dans mes documents.
Jamais personne ne m'en jamais parlé.
Conclusion : tout le monde réclame de la documentation mais personne ne la lit.

Un jour, j'avais commenté une fonction dans mon outil sur un ton plutôt léger, je me suis fait pécho par mon chef de projet qui m'a dit "imagine que monsieur G. [le sponsor du projet] vient lire ce commentaire ?". Ca m'éclate, déjà que je me dis que les test managers ne lisent même pas les dix cahiers de tests qu'on leur rend à la bourre le matin d'une mise en prod...

Ton histoire me fait penser au groupe Van Halen, qui demande, au milieu de la specification technique de leur préparation qu'ils envoyaient au concert, une coupe de M&M's dont on aurait retiré les marrons. Ce n'était pas un caprice du groupe, mais pour s'assurer que tout le document était lu en entier.

Mouarf sinon je suis tellement "pro" et je pense tellement à mon second que j'essaie de commenter absolument tout, de faire des docs de cahier de production, même si on me le demande pas.
Quand je viens en mission, j'en ai souvent des vieux, mais ça suffit déjà pour avoir une bonne base et savoir ou chercher, et quelle est l'architecture process globale du projet.
J'étais sur une mission où c'était codé comme des pieds, pour résumer vu de loin ça semblait très clair, une table source, une table cible, et un bloc fonction. Et le bloc fonction contenait une requête de sous-requêtes imbriquées de 5000 lignes. On comprenait pas pourquoi je galérais et que je mettais trois plombes pour dépatouiller le spaghetti
Et un jour à ma grande surprise, je tombe sur un "code" tout propre, de loin je comprends tout de suite ce que ça veut faire, y a juste un objet sur lequel je suis pas sûr. Je l'ouvre, et ô surprise, un commentaire qui m'explique tous les cas et justifie pourquoi le développeur a fait le choix de faire un truc aussi tordu. Mes CP étaient surpris : ils avaient vu le code de loin assez complexe, et étaient pas sûr que j'avais bien résolu l'anomalie en 30 minutes

Concernant les purs process, ça se fait à l'oral. Chez mon client actuel quand je dois faire une mise en prod, ça me prend facile 2h pour remplir toute la fiche, c'est vraiment casse-couille, pas intuitif et du coup j'oublie à chaque fois où sont les petits pièges.

[el_slapper]

(.../...)Concernant les purs process, ça se fait à l'oral. Chez mon client actuel quand je dois faire une mise en prod, ça me prend facile 2h pour remplir toute la fiche, c'est vraiment casse-couille, pas intuitif et du coup j'oublie à chaque fois où sont les petits pièges.

Et c'est là qu'un chef intelligent va te dire : "C'est long est chiant? Tu est informaticien? Automatises-moi tout ça!!!"

[Zirak]

Ton histoire me fait penser au groupe Van Halen, qui demande, au milieu de la specification technique de leur préparation qu'ils envoyaient au concert, une coupe de M&M's dont on aurait retiré les marrons.

Ca me fait toujours penser à :

Et me voila au Sri Lanka, anciennement Ceylan, à trois plombes du mat' a la recherche de mille M&m's bruns pour remplir un verre à dégustation sinon Ozzy refusait de monter sur scène ce soir-là ! Alors Jeff Beck passe sa tête à la porte et nous dit qu'il y'a un p'tit marchand de bonbons à la sortie de la ville. Alors on y est allé et manque de chance c'était fermé. Alors il a fallu que Keith Moun, David Krosby et moi on s'introduise dans la ptite boutique par effraction. Figurez-vous qu'au lieu d'un chien de garde, les enfoirés y'avaient un putain de monstre, un tigre du Bengale, une horreur ! Enfin, j'ai réussi à me charger du tigre avec une boîte de noix de muscade, mais pour le proprio et son fils malheureusement ça a été une autre paire de manches... J'ai été obligé de les battre à mort avec leurs propres godasses...

[Glutinus]

Et c'est là qu'un chef intelligent va te dire : "C'est long est chiant? Tu est informaticien? Automatises-moi tout ça!!!"

Non mais, c'est une appli-web en plus (enfin, qui fait appel à une autre appli-web type Jira, et également des fichiers Excel ).

La blague, c'est que le bloc 1, 2 et 3 se remplissent de la même manière, mais pour le bloc 4 il faut cliquer sur l'icône qui rajoute un bouton d'import de fichier EN BAS DE LA PAGE (après le bloc 17348) (c'est pas vraiment ça, mais c'est tout comme)

@Zirak : il y a des classiques que je n'ai pas vus, j'ai googlé pour voir la source. Ca doit pas être une coincidence qu'ils parlent des M&M's marrons justement. En plus c'est les meilleurs (j'ai appris que contrairement aux dragibus ou aux skittles, les goûts n'étaient pas différents entre M&M's )

[Zirak]

@Zirak : il y a des classiques que je n'ai pas vus, j'ai googlé pour voir la source. Ca doit pas être une coincidence qu'ils parlent des M&M's marrons justement. En plus c'est les meilleurs (j'ai appris que contrairement aux dragibus ou aux skittles, les goûts n'étaient pas différents entre M&M's )

Vu le thème / background du film, c'est même plus que fait exprès ^^

[el_slapper]

Non mais, c'est une appli-web en plus (enfin, qui fait appel à une autre appli-web type Jira, et également des fichiers Excel ).

La blague, c'est que le bloc 1, 2 et 3 se remplissent de la même manière, mais pour le bloc 4 il faut cliquer sur l'icône qui rajoute un bouton d'import de fichier EN BAS DE LA PAGE (après le bloc 17348) (c'est pas vraiment ça, mais c'est tout comme)(.../...)

C'est à ça que selenium peut servir, hein..... Si c'est chiant, répétitif, et qu'on se plante tout le temps, alors c'est prioritaire à automatiser.

EDIT : en plus, le script d'automatisation peut aussi faire office de doc. Ben oui, si tu regardes ce que fait le script, tu sais ce qu'il faut faire.....

[jmi57]

Bonjour,

Je reprends ce forum qui a quelques mois, car je voulais en gros poser la même question : quel est votre retour d'expérience sur la doc ?

J'ai fait pas mal de missions en SSII dans des grandes institutions, aussi j'ai vu pas mal de projets, certains avec trop de docs, dans d'autres trop peu...

C'est une question vaste, car il y a plusieurs sortes de doc :

• Process : Les tâches répétitives (livraison, installation d'un poste nouveau développeur, prise en compte de tickets, etc) sont expliquées pas à pas clairement dans un doc. Ca évite d'expliquer 40 fois la même chose... C'est du style "copie ce lien URL sur un navigateur" puis "clique là, puis là puis là", "envoie le mail ci-dessous à Machin en mettant à jour le numéro de version", "Ecris blabla dans une note du ticket Mantis concerné"
• Fonctionnel : SFG par exemple. Ca reprend toutes les règles fonctionnelles, les gestions IHM, etc... d'un point de vue plutôt MOA. La MOA ne connait pas toujours bien son application, et ne connais pas tous les impacts. Ce type de document doit être absolument complet et mis à jour très régulièrement sinon il ne sert à rien.
• Technique : On y trouve de tout, mais en général c'est plutôt axé sur des éléments qui vont aider les développeurs : comment fonctionne la PIC, la relation avec les autres applis, les différents couches du projet, etc...
• Par tickets : Dans certains projets, on fait de la doc par demande (analyse, fichier de tests). Ce sont des docs qui ne serviront que pour une livraison, puis on les met à la poubelle... Ca sert de cadrage et d'échanges avec la MOA, ainsi que de support en cas de régressions. Ces docs peuvent aussi servir de référence après une livraison pour mettre à jour les autres docs utilisables à long terme.
• Commentaire de doc / Javadoc : Pour moi, ça fait partie de la doc. Vaut-il mieux un batch de 10000 lignes très bien documenté ? Ou 10000 lignes sans commentaire mais accompagné d'un doc WORD de 150 pages ?

Quel que soit le support (WORD, WIKI, Excel, MagicDraw...), un doc peut être utile ou pas, non pas en fonction de son contenu, mais plutôt en fonction de ses mises à jour.
Un doc qui n'est pas mis à jour très régulièrement est une doc vouée à mourir.
Quoi de plus énervant de trouver une règle dans un doc, mais lorsque tu en parles, on te réponds que cette règle a changé en version XX.X.
Mais mettre à jour un doc est très couteux, c'est pourquoi il faut que le chef de projet et le client en soit conscient... Et c'est vrai que mettre à jour des docs n'est pas toujours très sexy comme travail pour le développeur.
Si la documentation est de très bonne qualité, même dans un répertoire avec 30 doc WORD de 200 pages, on peut trouver / modifier l'info en quelques minutes.

Je ne suis pas d'accord sur le fait de toujours "demander aux personnes compétentes".
La travail en équipe est très important, je suis d'accord. Mais la doc permet de regrouper les connaissances par écrit, même pour des domaines qu'on ne déterre qu'une fois tous les 3 ans...
Et puis les équipes sont parfois jeunes sur une appli qui existe depuis 20 ans (notamment en TMA mode forfait où les prestataires changent tous les ans).
Sur les gros projets, même la MOA demande de vérifier des règles fonctionnelles aux développeurs, car le mode de calcul de tel truc est géré par des lois de 1942 modifié par le décret 1965 et 1987 que tout le monde a oublié...

En tout cas, je dirai que dans tous les projets où la doc était inexistante, on passait des heures à essayer de comprendre une fonctionnalité, et les corrections/évolutions était beaucoup moins fiables (oublis, régressions, etc) que dans les projets très documentés. Mais à l'inverse, dans les projets très documentés, on passe des heures à mettre la doc à jour...

Voilà pour mon ressenti, j'attends vos commentaires

[el_slapper]

Sur les tâches répétitives : nôtre métier est de les automatiser, pas de les documenter.

Sinon, je suis un grand fan du code auto-documenté(points de bonus si ça génère de la vraie doc, mais c'est secondaire à mon sens). Avoir eu à refondre une appli de 36 ans d'âge influe fortement mon point de vue sur le sujet : en 36 ans, les on a forcément perdu toutes les docs, et les gens qui ont fait le code(et la doc) sont à la retraite ou morts. Et le code en question avait des numéros pour noms de procédures, et plein de goto partout, et des noms de variables en deux lettres.

Il existait forcément une doc qui expliquait tout ça en détail, mais elle a été perdue. Donc, j'ai procédé par essai-erreur, et il m'a fallu plus d'un mois pour comprendre(avant même de parler de le refaire) un seul composant de 4000 lignes. Et encore, la première partie de 1100 lignes, je n'en suis jamais venu à bout, j'ai du reprendre tel quel . Le reste, j'ai pu le comprendre, et faire du code auto-documenté, qui, si j'ai bien réussi, est parfaitement compréhensible sans doc ET sans commentaires...et dispose de commentaires quand même. Bon, je ne dis pas non plus que j'arrive toujours à cet idéal. Mais c'est mon idéal.

(oui, oui, 36 ans : écrit en 1972, refondu en 2008, logiquement, mon code sera refait en 2044, alors que la retraite sera proche pour moi, voire atteinte).

[jmi57]

Sur les tâches répétitives : nôtre métier est de les automatiser, pas de les documenter.

Je suis tout-à-fait d'accord.
Mais "automatiser" n'est pas forcément facile à mettre en place.
"Faire un doc WORD avec des impressions écrans", c'est plus accessible et ça peut se faire éventuellement en "sous-marin" pendant la tâche elle-même.

(oui, oui, 36 ans : écrit en 1972, refondu en 2008, logiquement, mon code sera refait en 2044, alors que la retraite sera proche pour moi, voire atteinte).

Comme quoi ça confirme mon avis : Je ne suis pas d'accord sur le fait de toujours "demander aux personnes compétentes".