Bonjour,
 
Je produit un petit soft, néanmoins un petit peu complexe et je désirerais documenter mon programme le mieux possible soit-il.
De manière générale :

• Que dois-je produire comme document ?
• Par quoi dois-je commencer ?
• Que ne faut-il documenter ?

De manière spécifique, (je suis sur Gnu/Linux)

• Que dois-je produire comme document ?
• Par quoi dois-je commencer ?

Avez vous des outils pour le développement de votre documentation, (j'utilise le langage Ada) ?
 
Pour ce que est des ficher sources du programme, je n'ai aucune idée du niveau minimum d'entendement de la programmation que je dois considérer pour commenter le code.
Je vais pas commenter les i := i+1; Quand même    Donc, si je ne commente que les algo spécifiques et que je fait un doc à part... ne puisse-t-il pas faire office de commentaire de code ?
Surtout que généralement, on utilise des lib qui sont pas à nous et donc déjà documenté, ou des algo du domaine public pour lesquels il existe carrément des Wiki
Merci.

La première chose est de savoir pour quel public : un prof ? un chef de projet ? un commercial ? un programmeur ? un utilisateur connaissant un peu l'informatique ? un utilisateur n'ayant pas besoin de se connaitre la cuisine interne mais voulant savoir se servir du soft ? un helpdesk ? autre ?
 
Généralement, on fait une doc pour chaque public visé : une doc utilisateur, une doc technique, et parfois une espèce de présentation commerciale. On peut faire plusieurs docs techniques : une pour une présentation générale, mais technique, et une autre pour expliquer certains points délicats.
 
Faire le maximum est le mieux, mais cela prend du temps et donc de l'argent. Donc généralement on fait le maximum en fonction de contraintes, et donc il faut avoir savoir les contraintes au début, et elles semblent floues pour vous.

Merci... Oui effectivement, il y à un public hétérogène, et justement, en parlant de contraintes, je désirerais faire un effort pour mettre le programme à la porter de chacun sous l'angle utilisateur, (mais à part ça, j'ai le temps). Mais je désirerais également permettre au érudits de se plonger dans le code.
Je ne pense pas faire de doc commerciale, mais je doit tout de même présenter le soft à chacun donc.
Donc, faire une documentation utilisateur et développeur, Pour les utilisateur, je doit distinguer la documentation utilisateur et administrateur.
Qu'est-ce qu'un helpdesk ?

D'un point de vue processus de développement, tu aurais dû produire :
- Le DSL (dossier de specs)
- le DCP (dossier de conception, plus ou moins détaillé)
- le dossier de tests (plan de tests et résultats de tests, mais ça peut faire l'objet de 2 docs)
- le MINST ou le MEX (manuel d'installation ou d'exploitation, en gros, comment paramétrer le bousin et y mettre les solutions aux pbs classiques rencontrés dû à un mauvais paramétrage -> pratique pour un help-desk)
- le MUT (manuel utilisateur)
 
Après, si le MUT est gros, c'est bien de faire des plaquettes de prise en main rapide, éventuellement une par profil utilisateur (si y'a plusieurs rôles dans l'apli).
Pour le commerciale, une plaquette de présentation sexy, c'est bien aussi.
C'est bien aussi de faire un PPT de présentation rapide de toutes les fonctions pour le chef de projet.
 
Plus spécifique au help-desk, mettre en palec une base de connaissances avec les pbs courants rencontrés et leur solution.

Merci... Alors je suis bien embêté parce que j'ai beaucoup de mal à produire le cahier des charges.  
Je suis pourtant bien demandeur d'un service : je veux produire un agent de dialogue intelligent.
 
Qu'est-ce qu'un agent de dialogue intelligent ?
 
 - C'est un programme capable de :  
   

• dialoguer avec un ou plusieurs utilisateurs ;

• organiser des conférence entre les utilisateurs ;

• tenir une conférence ;

• produire des comptes rendus sur les conférences.

Je jette ça comme ça.. En fait c'est bien plus...
 - C'est un programme capable également de :
   

• enregistrer des information sur le réel

       afin de les publier dans un environnement
        informatique.
   

• acquérir des informations sur un  

       environnement informatique afin de les
        intégrer à son discours.
 (les affections et effections du système)
 
A partir de là que puis je faire ?
 
En complément je souhaite :

• protéger les accès et sotie des programmes client et serveur par mot de passe.

 
Voila, j'ai beaucoup de mal à me placer dans la peau d'un simple demandeur.

Ben si t'as déjà du mal à définir le périmètre fonctionnel de ton programme, tu vas bien être en peine de le développer

"définir le périmètre fonctionnel"... N'est-ce pas ce que j'ai fait dans mon précédent message ?
Ca te parait-il insuffisant ?

 
C'est pas moi qui le dit, c'est toi... La réussite d'un projet informatique (mais ça doit probablement s'appliquer à n'importe quel projet) passe d'abord par une expression de besoin claire, précise et bornée. Il faut exprimer les exigences en termes S.M.A.R.T. (en gros, une exigence doit exprimer une seule idée, doit être vérifiable, quantifiable, mesurable...).
 
Y'a des outils genre DOORS qui permettent de gérer les exigences et de générer le dossier des exigences automatiquement

Je trouve rien sur un logiciel DOORs qui ferais ça... T'aurais pas un petit lien ... ?

Google -> "logiciel doors" tout simplement
 
http://www.knowllence.com/fr/produ [...] elogic.php

 
Ah oui, je suis tombé dessus, mais je ne pensais pas que c'était celui-ci.
Merci rufo

 
J'avais tout de même exprimé un certain besoin... Non ?
DOORS, je trouve pas le lien download, je suppose qu'il faut raquer 10¨plaques... que j'ai jamais.
J'ai peur aussi que ce soit un peut trop pointu pour moi.

Mouais, t'as "peur" d'utiliser un truc pointu, alors que ce tu veux faire est extrêmement pointu... on touche les limites des connaissances actuelles, sans parler des limites de la calculabilité, des générations de chercheurs se sont cassés les dents là-dessus et tu penses qu'en mettant 2 ou 3 bullet point, tu vas cerner le problème ?
 
Moi, j'appelle ça le syndrome MultiDeskOS : trop ambitieux, des idées belles sur le papier, mais quasi irréalisable en pratique, car trop flou, impossible de décortiquer le problème en éléments plus simple, histoire de pouvoir mesurer les progrès. Car sans mesure, tu auras l'impression de faire du sur place, et ta motivation va décroitre exponentiellement.
 
Désolé pour le ton cassant, mais je crois sincèrement que tu iras nulle part avec des besoins aussi mal spécifiés. Besoins dont il est inutile d'avoir un logiciel aussi cher soit t-il pour les exprimer. Du bon sens et une feuille de papier, ça sera déjà pas mal (et accessoirement connaître les limites des technologies actuelles, ça serait bien aussi).

Doors est très cher, c'est clair. Je parlais de ça car il donne un cadre assez précis pour définir et modéliser les exigences (avec les relations entre elles + exigences induites).
Ce que dit tpierron rejoins mes propos sur le formalise d'une expression d'une exigence : méthode SMART => 1 exigence = 1 idée simple, mesurable (pour contrôler l'avancement), réaliste et bornée.
 
SMART est un acronyme anglais, chaque lettre donne 1 des 5 caractéristique de ce que doit être une exigence. En +, c'est exprimé avec sujet, verbe d'action, complément, ex :

Je vous dis que je vais faire une doc, pour un soft qui fonctionnera, qu'il soit fonctionnel ou pas.

Bonjour,
Je viens voir si avec votre aide je pourrais pondre une documentation à la hauteur du projet sur lequel je travaille (heu, aujourd'hui).
 
Il s'agit d'un agent de dialogue basée sur les réseaux de neurones artificiels. C'est écrit avec Ada et GtkAda.
Alors je ne veux pas entrer dans le détail qui est de savoir si oui ou non ce truc est intelligent ou pas.
Je veux une doc pour les utilisateur et éventuellement une doc pour l'adapter à ses besoins.
 
Voici mon document actuellement, vous trouvez le paquet U2 contenant normalement ce doc dans ma signature.
 

Dans ce programme j'utilise la bibliothèque de réseaux de neurones artificiel de PragmARC.
Voilà, je suis toujours à la bourre sur la doc, maintenant faut que je rattrape.
Merci pour vos remarques vos conseil, et votre gentillesse.

Ca, c'est pas une doc, c'est un readme vue la longueur
 
Il faudrait au moins faire un MEX qui explique comment installer ton programme, comment le configurer, avec des exemples concrets... Il devra aussi traiter les principales raisons pour lesquelles le programme ne fonctionnerait pas : donner les msg d'erreur que l'on pourrait rencontrer et comment y remédier avec la cause la plus probable ayant entraîné ces msg d'erreur (ex : fichier d'entrée ou de sortie mal formaté, chemin d'accès de certains fichiers mal configurés...).
 
Le MUT sera moins technique et expliquera comment utiliser le programme, avec des textes et captures d'écran...

Merci encore rufo, Le MEX et le MUT en version longue c'est quoi ?
Comment construire de tels documents?

Ex de plan d'un MEX :
Sommaire
1 BUTS DU DOCUMENT
1.1 BUTS
1.2 GUIDE DE LECTURE
2 DOCUMENTS APPLICABLES ET DE REFERENCE
2.1 DOCUMENTS APPLICABLES
2.2 DOCUMENTS DE REFERENCE
3 TERMINOLOGIE
4 ARCHITECTURE DU SYSTEME
5 INSTALLATION / PARAMETRAGE DU SYSTEME
5.1 Prérequis
5.1.1 Connaissances techniques
5.1.2 Configuration de la machine hébergeant l’application
5.1.3 Logiciels nécessaires
5.2 Installation
5.2.1 Première installation de l’application
5.2.2 Installation d’une nouvelle version de l’application
5.2.3 Droits d’accès sur certains répertoires
5.3 Paramétrage du système
5.3.1 Paramétrage du fichier de configuration
5.3.2 Paramétrage de xxxxxx
5.3.3 Paramétrage de yyyyyyyy
...
6 EXPLOITATION
6.1 Mise en route
6.1.1 Mise en route des matériels
6.1.2 Lancement du système
6.2 Arrêt
6.2.1 Arrêt du système
6.2.2 Arrêt des matériels
6.3 Reprises
6.4 Procédures courantes en fonctionnement normal
6.4.1 Procédure de création du fichier xxxxxx
6.4.2 Extraction/exportation de données
6.4.3 Importation de données
...
6.5 Procédures sur incidents et pannes
6.5.1 Procédures communes
6.5.2 Etablissement du diagnostic
6.5.3 Traitement des problèmes
6.5.4 Traitement des problèmes en contexte particulier
7 ANNEXES
 
 
Bien entendu, certains § peuvent être supprimés si pas applicables.

Ex de plan type pour le MUT :
 
Sommaire
1 BUTS DU DOCUMENT
1.1 BUTS
1.2 GUIDE DE LECTURE
2 DOCUMENTS APPLICABLES ET DE REFERENCE
2.1 DOCUMENTS APPLICABLES
2.2 DOCUMENTS DE REFERENCE
3 TERMINOLOGIE
4 PRESENTATION GENERALE
5 PROCEDURES DE MISE EN OEUVRE
5.1 MISE EN ROUTE
5.2 CONDITIONS D’UTILISATION
5.2.1 Profils d’utilisateurs, droits et protections d’accès
5.2.2 Procédures
5.3 ARRET
6 PRESENTATION DES ECRANS DE L’IHM
6.1 MODES DE DIALOGUE
6.2 STRUCTURE DE L’ECRAN  
6.3 OBJETS DU DIALOGUE
6.4 SYNTAXE DU DIALOGUE
6.5 ACTIONS REPETITIVES, PROCEDURES GENERALES
6.6 CONVENTIONS DE REPRESENTATION
6.7 LOGIQUE DE CHEMINEMENT
6.8 AIDE EN LIGNE
7 DEMARCHE D’UTILISATION
7.1 Description fonction n°1
7.1 Description fonction n°2
...
8 ANNEXES

Merci beaucoup rufo.