Meilleures pratiques de Documentation d’un Projet TI; l’objet de la documentation

Voir la version AMP

Les meilleures pratiques de Documentation d’un Projet TI ne sont pas simples car l’objet de la documentation n’est pas toujours évident. D’abord, dans un projet TI, on peut retrouver un grand nombre de documentations différentes; le fameux manuel de l’usager, la documentation des requis destinée à l’exploitant du logiciel, la documentation d’architecture et de design destinée aux analystes, designers et développeurs et finalement, la documentation technique ou documentation logicielle destinée aux programmeurs en sont les principaux exemples.

Bref, la documentation d’un Projet de Développement logiciel, c’est comme les assurances, ça en prend mais il faut trouver le bon équilibre.

En ce qui nous concerne, nous parlerons de la documentation d’architecture et de conception et de la documentation technique d’un projet de développement TI. Ainsi, que doit-on documenter ?

Dans cette série de billets, nous allons aborder les points suivants :

  • Que doit-on documenter dans un projet TI ?
  • Comment doit-on documenter ?
  • Où doit-on rendre disponible ces documents aux différents lecteurs ?

Qu’est-ce qui devrait être objet de Documentation d’un projet TI ?

 

Pour déterminer ce qui doit être documenté, il faut tenir compte de :

  • de ce qui doit être livré; l’application
  • des différents intervenants
  • de l’environnement

Les étapes d’un projet de développement logiciel sont généralement les mêmes, peu importe le projet :

  • Requis
  • Planification (Versions et Sprints)
  • Design
  • Développement
  • Tests
  • Déploiement

Selon ces étapes, les documents potentiels à livrer sont les suivants :

schéma documentation

D’abord, avant de commencer un projet TI, normalement l’entreprise possédera plusieurs documents :

  • Les standards de l’organisation
    • La nomenclature
    • La façon de nommer les objets
  • Les standards de conception et de réalisation (codage) de l’organisation
    • Les normes de documentation
    • L’architecture de développement
    • Définition des « couches », des classes, des méthodes etc.
    • La façon de nommer les objets
    • Les normes de test
  • Pour le projet lui-même, nous avons une panoplie de documents potentiels à produire. Nous allons associés ceux-ci aux différentes étapes du processus de développement logiciel :

REQUIS

  • Nous incluons dans cette phase les différentes rencontres nécessaires pour comprendre la demande du client. Un compte-rendu de réunion doit nécessairement être produit après chaque rencontre.  Celui-ci devrait contenir les éléments suivants :
    1. Le ou les sujet(s) de la rencontre
    2. Responsable(s) par sujet
    3. Objectif(s) du sujet : Information, Échanges, Consultation, Génération d’idées, Décision
    4. Durée maximale :
    5. Compte-rendu : Compte-rendu et décision(s) sur le sujet

N.B.  Le traitement des « To Do » de ces réunions sera discuté dans un autre billet

  • Le document des spécifications fonctionnelles est définitivement un des documents les plus importants. Il traduit les besoins d’affaires du client en requis pour les développeurs. Selon la taille du livrable, il pourra être très court ou très long, mais il est toujours obligatoire.Chez Analystik, le document est d’autant plus utilisé que nous l’alimentons tout au long des développements car nous y ajoutons les spécifications techniques.

Chez Analystik, le document des spécifications fonctionnelles couvre les éléments suivants :

Exigences d’affaires (Business Requirements – BR)

  • Objectif du projet
  • Exigences d’affaires
  • Hypothèses
  • Exigences d’affaires exclues de la portée du projet
  • Annexes
  • Planification
  • Approbation

Exigences fonctionnelles (Functional Requirements – FR)

  • Objectifs du livrable
  • Spécifications fonctionnelles
  • Hypothèses
  • Exigences fonctionnelles exclues de la portée du projet
  • Annexes

 

PLANIFICATION

  • Chez Analystik, la planification s’exécute à l’aide de l’outil Microsoft TFS (Team Foundation Server) Cloud. Toute la documentation produite se retrouve dans l’outil.  On y retrouvera, les Epics, les Features, les User Stories et les Tasks.  La beauté de la version Cloud de cet outil est que tous les intervenants du projet y ont accès, les clients compris.

DESIGN

  • Une bonne pratique consiste à obliger les développeurs à prendre le temps nécessaire pour designer la fonctionnalité qu’ils ont à livrer avant de commencer à coder. Souvent chez Analystik, ceci prend la forme de schémas UML comme celui-ci :
UML schematics

DÉVELOPPEMENT

  • Pour le développement, dans le meilleur des mondes, le premier document à produire serait le Plan de Tests de la fonctionnalité à produire. Par contre, soyons honnête, tant que la culture du Test Driven Development ne sera pas parfaitement mise en place, le Plan de Tests est souvent produit plus tard dans le processus.
  • L’autre documentation à produire n’est pas un document mais bien une documentation incluse dans le code. Oui, oui, on parle bien des COMMENTAIRES !

Malheureusement ici, on peut difficilement parler de bonne pratique d’entreprise car la quantité et la qualité des commentaires ont toujours été et seront toujours fonction de la personnalité du développeur…  malgré les revues de code et autres mécanismes de validation.

TEST FONCTIONNEL

Pour chaque fonctionnalité, il faut définir l’objectif du test, les étapes ainsi que les résultats attendus. Notre grille de plan de test ressemble à ceci :

Test Plan

DÉPLOIEMENT

  • Encore une fois pour le déploiement, la documentation peut être minimaliste, tel un site Web simple chez un fournisseur, ou très complexe; par exemple une application Windows critique déployée sur des centaines de postes et des environnements hétéroclites.

Dans ce dernier cas, on aura plusieurs phases de tests, différents environnements de « Évaluation de Qualité » et des outils de suivi seront utilisés pour compiler et suivre les tests, des outils comme Team Foundation Server Cloud, JIRA…

 

Conclusion

Évidemment, selon l’application à livrer les différents intervenants, et l’environnement dans lequel l’application roulera, une panoplie d’autres documents peuvent être exigés.  En voici quelques exemples :

  • Devis
  • Plan de projet
  • Daily Scrum – Suivi des obstacles
  • Liste des actions à suivre
  • Suivi des heures et des montants
  • Liste des livrables
  • Suivi de l’assurance qualité des livrables
  • Comptes rendus

Il est donc important de trouver un juste équilibre dans la documentation car, malheureusement, celle-ci n’est pas gratuite et son coût peut varier de 10% à plus de 100% des coûts de développement

Il faut retenir les bénéfices suivants de la documentation d’un projet de développement TI :

  • Pérennise l’application livrée en facilitant son évolution (mise à niveau)
  • Facilite le support (troubleshooting)
  • Minimise le risque de l’entreprise à plusieurs niveaux en lui donnant une certaine autonomie en regard de son équipe de développement TI ou de ses fournisseurs TI

 

D’un autre côté, la documentation d’un projet TI allonge les temps et les coûts de développement.

 

Bon projet de développement,

 

Denis Paul & Michel

Laisser un commentaire

Votre adresse courriel ne sera pas publiée. Les champs obligatoires sont indiqués avec *