Documentation sur la documentation

Bonjour

Je cherche a faire une documentation de qualite sur differents developpements et applications.

J'aimerai trouver des documents de reference :
- documentation pour l'utilisateur
- documentation pour qu'un developpeur puisse me remplacer
(architechture, conception...)

J'ai bien sur un peu notion de ce qu'il faut apres mes exepriences.
Je cherche des documents de reference sur le sujet ou des informations sur les bonnes pratiques.

Merci

Bonjour,

Ahh, difficile sujet que la documentation. Rassurez-vous, vous n'êtes pas le seul à y avoir pensé.
La première documentation (et la plus fondamentale) est bien sur l'ensemble des documents/graphiques/dessins (appelés artefacts) créé lors de la conception. Traduit en français courant: les diagrammes UML par exemple ! Ceux-ci reflètent, normalement, l'architecture et le fonctionnement technique de l'application.

En termes de documentation utilisateur, à ma connaissance, c'est beaucoup plus libre. Wiki, guide d'utilisation, présentation avec des diapositives dont autant de manières de communiquer avec les utilisateurs.

Cordialement,
Elverion

Je me dévoue, histoire de m’occuper et de vous distraire… mais c’est très personnel, je ne dis pas que c’est comme ça qu’il faut faire mais que c’est comme ça que je faisais. Ce ne sont donc pas des paroles d’évangile. On enseigne les langages et l’algorithmique mais pas les bonnes pratiques. Il appartient à chacun de chercher sa vérité en lisant, en pillant ce que font les autres, en créant ses propres bonnes pratiques.

Concernant la documentation pour l’utilisateur, le sujet a été abordé ICI.

Pérenniser ses investissements n’est pas qu’une question de documentation mais de bonnes pratiques de programmation et de développement… Enfin, en ce qui me concerne, mes bonnes pratiques de développement sont un peu particulières car j’ai toujours développé sans étude préalable, ni cahier des charges. La méthodologie de développement n’étant pas le sujet, je peux quand même vous faire partager mes bonnes pratiques (plus ou moins pertinentes) dans le cadre de mes développements « Botom-up » et de ce qui a été mon domaine de compétence : la gestion, un SGBD (Informix mode caractères) et unix. Internet est arrivé trop tard pour moi.

Je vais essayer de respecter le sommaire ci-dessous… sachant que j’ai beaucoup de difficultés à intervenir sur le site. Il me reconnait mais ne me voit pas toujours connecté et ne m’affiche pas le bouton « Editer » bien que je sois autorisé à modifier.

Bonnes pratiques de programmation

• Règles de mise en page des programmes
• Méthodologie (traitements batch)
• Noms de tables
• Noms de données (normalisation sémantique et syntaxique)

Documentation intégrée

• Brainwriting
• Mémorandum
• Newsletter
• Générique
• Charte, conventions, symbolisme
• Sous-menu « INFORMATION - DOCUMENTATION »

Documentation SGBD (AGL minimaliste)

• Arborescence des développements
• Modélisation des données
• Tables système
• Dictionnaire des données (tables SYS_TAB et SYS_COL)
• Table des développements « écrans, états , shells, sqls »

Documentation à posteriori

Règles de mise en page des programmes

Même les langages structurés ne peuvent pas empêcher de programmer sans rigueur. Il appartient à chacun de créer ses propres bonnes pratiques de programmation. Ça n’est pas vraiment de la documentation mais des règles de mise en page à l’instar des règles de mise en page des livres. Personnellement, j’ai besoin d’au moins deux mois pour m’installer dans un nouveau langage, pour créer ce que j’appelle ma structure d’accueil.

Je peux proposer un exemple concret pour illustrer mon propos mais j’ai besoin d’un peu de temps pour le commenter.

Ma structure d'accueil a pour objectif de définir les conventions adoptées, les règles d'écriture et de présentation des programmes :

• squelette de programme (canevas d’écriture),
• identification du programme,
• méthodologie de programmation,
• utilisation des majuscules et des minuscules,
• indentation,
• noms de variables communs à tous les programmes de l'application,
• règle d'écriture des paramètres et variables spécifiques,
• shell d'exécution, sous forme de commentaire, en fin de programme.

Une fois définie pour un langage, la difficulté réside dans son adaptation aux spécificités d'un nouveau langage. Une structure d'accueil n'a rien de contraignant car chaque nouveau programme s'écrit à partir d'une copie de programme(s) existant(s), et les éditeurs permettent de faire facilement des copier-coller. Certains développeurs pourraient cependant y voir un frein à leur créativité. Concevoir une structure d'accueil, n'est-ce pas précisément faire preuve d'imagination ? Certes, il s'agit de s'investir sur l'esthétique, la présentation, la lisibilité plutôt que sur les astuces de programmation, mais quel est l'intérêt de réinventer l'eau chaude à chaque nouveau programme ?

L'objectif de la structure d'accueil est de rendre le programme aussi lisible qu'un document écrit afin d'éviter le recours à tout dossier d’analyse ou de programmation, à tout organigramme. Tous les programmes étant construits d'après la même architecture, il suffit à une tierce personne de saisir le fil conducteur, de comprendre la logique qui a régi l'un des programmes de l'application pour qu'elle « décode » tous les autres sans difficulté. Rien n'est plus décevant, angoissant, déprimant que d'intervenir dans un programme sans personnalité, sans repères, sans la moindre trame décelable, susceptible d'en guider la lecture. Certains artifices de forme ne sont pas à négliger. WINDEV, Delphi, les éditeurs utilisent la couleur pour distinguer instructions, données et variables. Dans le même esprit, sous UNIX, le seul fait d'utiliser des majuscules pour les instructions et des minuscules pour les données ou variables améliore considérablement la lecture des programmes (le compilateur Informix traite indifféremment les majuscules et les minuscules). En rendant les instructions suffisamment compréhensibles, les traitements se passent de commentaires. En résumé, un programme est un tout, pas seulement un cocktail de codes commentés, mais un véritable document lisible, digeste qui se suffit à lui-même.

Méthodologie (traitements batch)

Conception et réalisation s'appuient sur les principes méthodologiques de base (CORIG, LCP, modèle entités-relations) sans la contrainte d'outils sophistiqués à mettre en œuvre (AGL de conception, AGL de réalisation). Un Environnement de Développement Intégré (IDE) doit suffire.

LCP : Logique de Conception de Programme (Méthode Warnier)

Pratiquer LCP suppose de penser par traitements et non par conditionnements. Formatés « programmation sauvage », rééduquer ses neurones pour « penser par traitements » nécessite un effort mental important car il faut résister au déviationnisme satisfaisant ses vieux réflexes. Ceux qui critiquent LCP n’ont vraisemblablement jamais intégré ce principe fondamental qui s’applique d’ailleurs dans bien d’autres domaines.

La méthode LCP est indépendante du langage : un contributeur sur Wikipédia prétend le contraire (Discussion : programmation structurée) : « La programmation en Warnier se fait par branchement (GO TO) ». L’auteur de ce propos n’a vraiment rien compris à LCP. Cela dit, pratiquer LCP avec un langage qui ignore le « GO TO » comme le compilateur « ace » d’Informix nécessite une autre forme d’effort mental pour « fixer » ses repères et les adapter à son nouvel environnement de développement.

La méthode LCP est indépendante de la typologie du développement : certains pensent que LCP n’est adaptée qu’aux problématiques de gestion. Sans doute parce que selon ses principes, la structure hiérarchique d'un programme se déduits logiquement de la structure des données utilisées, la construction du programme commençant par la structuration des données qu'il doit produire en sortie.

Cette perception n’est pas fausse si l’on n’a pas dépassé le premier niveau de conceptualisation. Passé l’apprentissage de la méthode, LCP peut se résumer par ce seul principe fort : « penser par traitements ». Dès lors, LCP peut s’appliquer quel que soit le domaine.

LCP, c’est trois niveaux de conceptualisation :

• Parenthèses -> Organigramme -> Programmation :
  Pédagogie (formateur) : durée = 1 semaine
  Initiation (stagiaire) : durée = 2 à 3 semaines

• Organigramme -> Programmation :
  Apprentissage : 1 à 2 mois par type de programme (Contrôle/Mise-à-jour/Edition/Interactif)

• Développement à main levée :

Expérience : toute sa carrière

Ces trois niveaux de conceptualisation peuvent être assimilés aux trois niveaux de lecture :

1. Lecture syllabique
2. Lecture mot-à-mot
3. Lecture rapide

Passer du premier au deuxième puis au troisième niveau, donc s’affranchir des parenthèses et de l’organigramme nécessite un effort mental, la volonté de s’approprier la démarche.

Un langage dit « structuré » comme « ace » de l’EDI Informix, à base de SQL, permet de déclarer des blocs « BEFORE » - « AFTER » et des blocs « PAGE HEADER » - « PAGE TRAILER » qui ne sont rien d’autres que les « DEBUTS TRAITEMENT» et « FINS TRAITEMENT» de LCP ; la décomposition hiérarchique des traitements (du général au particulier) se réalisant par une simple clause « ORDER BY ».

Noms de tables

Je les limite de préférence à quatre caractères maximum. Dans les programmes, les noms de données sont impérativement préfixés du nom de la table à laquelle ils appartiennent (règle SQL). Cela se pratique depuis que le COBOL existe avec les étiquettes logiques associées aux fichiers.

Noms de données (normalisation sémantique et syntaxique) :

Le RAD propose d’abréger les noms de données de façon significative et unique, respectant en cela six règles de normalisation sémantique et syntaxique, règles que l'on pratique le plus souvent sans le savoir et que l’on pratiquait déjà bien avant le RAD.

Abréviations : Personnellement, j’évite les abréviations à l'exception des quatre lettres :

- "C" pour Code,
- "T" pour Type,
- "N" pour Numéro,
- "L" pour Libellé,

Toutes les tables de références (Communes, Départements, Nomenclature, etc.) possèdent un code ou un numéro, parfois un type et toujours un libellé. Ces noms de données sont constitués très simplement du nom de la table à laquelle ils appartiennent, préfixé par la lettre mnémonique, "C" pour Code, "N" pour Numéro, "T" pour Type et "L" pour Libellé. Ainsi, une table des communes nommée "cm" aura (entre autre) pour noms de données :

cm.c_dp, (code département)
cm.c_cm, (code commune)
cm.t_cm, (type commune)
cm.l_cm, (libellé commune)
cm.n_cp, (numéro de code postal)

Il peut cependant y avoir des exceptions comme pour la table des codes postaux par exemple :

cp.n_cp, (numéro de code postal)
cp.l_ld, (libellé lieu distribué au lieu de libellé code postal)

Sans en abuser, rien n'interdit d'étendre le principe à d’autres identifiants. Par exemple : « s » pour « session ». Ces abréviations simplifient, améliorent la lisibilité et facilitent l’écriture des requêtes sql.

A signaler que dans les programmes, les noms de données gagnent à être renommés de la façon suivante afin d’éviter d’avoir à préciser leur table d’appartenance :

cm.c_dp cm_c_dp,
cm.c_cm cm_c_cm,
cm.t_cm cm_t_cm,
cm.l_cm cm_l_cm,
cm.n_cp cm_n_cp, etc.

A tout endroit d'un programme on sait quelles données l'on manipule. Les erreurs éventuelles sur les noms de données sont essentiellement des erreurs de saisie facilement repérables. A noter, sans l'imposer, que les variables d'un programme se référant d'un nom de donnée peuvent être préfixées de la lettre "V" et les paramètres, de la lettre "P".

Les éléments commentés ci-dessous font l’objet d’un sous-menu de l’applicatif « INFORMATION - DOCUMENTATION » :

BRAINWRITING

J'avais pour habitude de rédiger sur une feuille de listing pliée en deux que je gardais à portée de main sous mon clavier, une liste de ce que je prévoyais de faire avec un ordre de priorité, un peu comme l'on fait une liste pour faire ses courses. Et de la même manière, je raturais au fur et à mesure ce qui était fait.

Lorsque cette liste que j'annotais et que je complétais au gré des sollicitations et de mes élucubrations, finissait par perdre de sa lisibilité, j'en dressais une nouvelle qui reprenait ce que je n'avais pas encore réalisé.

Plutôt que de garder mes bouts de papier sous mon clavier et de les jeter lorsqu'ils étaient devenus obsolètes, j’ai fait profiter les gestionnaires de ces informations dans une rubrique du menu de leur application. En consultant cette rubrique, ils peuvent se tenir au courant de ce que je leur concocte.

L’ordre de priorité des idées et projets d’aménagement, d’abord chronologique évolue selon l’urgence et la pertinence des objectifs.

La réalisation d’un objectif entraine sa suppression du brainwriting et la création d’un item dans l’historique des modifications : le Mémorandum.

MEMORANDUM

Le MEMORANDUM historise le développement incrémental.

A l’origine (1971), nous consacrions en fin de journée un petit ¼ d’heure à résumer l’activité de la journée dans un cahier.

Le cahier, devenu un fichier texte s’est ensuite transformé en outil de communication suite à l’exportation d’une application en cours de développement. Cahier des charges « live », ce document (avec les newsletters) fournit le matériau pour la constitution d'une documentation à postériori plus élaborée, en gestation sous PowerPoint.

NEWSLETTER

Il s'agit d’informer les gestionnaires des dernières évolutions de leur application ou de rappeler, préciser, compléter une de ses fonctionnalités.

Les "newsletters" évitent de perdre du temps à consulter les rubriques qui ne se sont pas enrichies récemment. Ils y trouvent donc, entre-autre, les dates de mise à jour de toutes les rubriques et une indication sur le contenu de la mise à jour.

GÉNÉRIQUE

L’application est considérée comme une œuvre de l’équipe ad hoc constituée de l’informaticien, de l’utilisateur (responsable du département métier) et de ses gestionnaires. Comme pour un film, le générique cite toutes les personnes ayant participé à l’élaboration de l’œuvre. Avec le temps, l’équipe évolue, le générique est un moyen d’intéresser, de motiver une nouvelle recrue intégrant l’équipe. Il est attendu de sa part qu’elle apporte sa contribution au logiciel.

CHARTE, CONVENTIONS, SYMBOLISME

La charte graphique adoptée s'arrange au mieux de la contrainte du mode caractères. Elle s'applique à l'application et à tous les documents qu'elle produit. L'application elle-même, dans ses menus et ses shells, fait appel à un symbolisme limité et très compréhensible.

La lecture des items du menu est facilitée par l'utilisation du symbolisme suivant :

[] symbolise un écran
>> symbolise l'appel d'un sous-menu
[i] symbolise l'affichage d'informations à l'écran
[?] symbolise le traitement permettant d'envoyer à l'imprimante le résultat d'une requête écran. Cela équivaut à une touche "Impr. écran" plus sophistiquée. Dans l’application, tous les écrans ont la même taille et sont imprimées trois par page.

NB : les items exempts de symbole exécutent un traitement piloté par un shell ou un sql.

SOUS-MENU « INFORMATION - DOCUMENTATION»

Code:

---

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17

INFORMATION DOCUMENTATION 01. INFORMATION 15. DOCUMENTATION 02. L’APPLICATIF 16. A PROPOS DE L'APPLICATIF 03. CONNEXION 17. INSTALLATION DE L'APPLICATIF 04. LEXIQUE 18. METHODOLOGIE 05. LE MENU 19. ARBORESCENCE 06. LES TABLES 20. DICTIONNAIRE DES INFORMATIONS 07. LES ECRANS 21. CHARTE, CONVENTIONS, SYMBOLISME 08. LES EDITIONS 22. ERGONOMIE, CONVIVIALITE, DESIGN 09. CONSIGNES D'ORGANISATION 23. 10. BRAINWRITING 24. 11. MEMORANDUM 25. 12. NEWSLETTERS 26. DEVELOPPEMENTS (1) [] 13. GENERIQUE 27. DEVELOPPEMENTS (2) [] 14. 28.

---

Gérer ses développements dans l'application elle-même pour ne pas être le cordonnier le plus mal chaussé :

• Arborescence des développements
  
  Ensemble des répertoires et sous-répertoires de l’applicatif avec indication du nombre de lignes développées.

• Modélisation des données
  
  Entités-Relations par grandes fonctionnalités.

• Tables système
  
  Une édition liste toutes les tables de la Base de données pour s'y retrouver dans les tables, les vues et les synonymes.
  
  - Noms des tables (mnémoniques)
  - Nombre de colonnes
  - Nombre de rangées
  - Synonymes
  - Vues
  - Noms des tables (libellés)

• Dictionnaire des données (tables SYS_TAB et SYS_COL)
  
  L’ajout d’une table « SYS_TAB » aux tables système permet de renseigner le nom étendu (libellé) des tables sans prendre le risque de modifier la table système « SYSTABLES ».
  
  L’ajout d’une table « SYS_COL » aux tables système permet de commenter chaque information sans prendre le risque de modifier la table système « SYSCOLUMNS ».
  
  Un écran permet de connaître l'impact d'une éventuelle modification, de voir tout de suite sur quelles tables intervenir pour rester cohérant.

• Table des développements « écrans, états, shells, sqls »
  
  Cette table permet de savoir si les développements sont liés et d’imprimer des listes par type de développement. Cette table se charge facilement à partir d’un petit shell unix et d’une requête sql.
  
  - Type (écran, état, shell, sql)
  - Nom
  - Objet
  - Nombre de lignes

Il s’agit de constituer un outil unique de formation, d’auto formation qui soit un véritable cahier des charges en vue d’entreprendre plus classiquement mais sans « effet tunnel » un nouveau développement de l’applicatif avec les outils et moyens du moment. Plusieurs logiciels permettent sans doute de réaliser ce genre de documentation, PowerPoint par exemple.

Cela suppose :

• que l’applicatif soit arrivé à maturité afin que l’allègement progressif du temps de développement permette l’investissement,
• que l’organisation ad’ hoc ait été normalisée (bureaucratisée),
• que l’investissement soit rentable, c’est-à-dire que les dirigeants comprennent la nécessité de redévelopper une nouvelle application.

L’expérience révèle que l’application existante leur donnant toute satisfaction en l’état, les dirigeants ne voient pas l’intérêt de réinvestir dans un nouveau projet. L’informatisation de la problématique se dégrade inéluctablement par l’obsolescence progressive des moyens matériels et logiciels mis en œuvre. La veille technologique est une vaine préoccupation et l’on s’achemine en fin de compte vers la situation de crise à l’origine des développements. L’histoire n’est qu’un éternel recommencement.

La documentation à postériori, lorsqu’elle a la chance de se concrétiser invente un cahier des charges bien loin du cahier des charges classique.