Documenter tous les aspects d’un projet : check-list

Introduction

Tout au long de la vie d’un projet, celui-ci doit être documenté soigneusement. La documentation est gérée en configuration (versions), au même titre que le code : elle fait intégralement partie du projet et doit être livrée sans décalage avec la production des éléments techniques.

De nombreuses directions informatiques possèdent des processus d’assurance qualité et se conforment à des normes ayant pour objet de garantir que, de projet en projet, leur production de logiciel est mature et ne régresse pas sur différents critères. Un des auteurs de cet ouvrage a eu l’occasion de faire certifier le niveau de maturité de plusieurs grandes organisations informatiques au regard du référentiel CMMI (Capability Maturity Model Integration), aujourd’hui en version 2, de l’ISACA (l’ISACA implique plus de 140 000 membres et professionnels titulaires de certifications dans plus de 180 pays).

La présente check-list est en quelque sorte le fruit de cette expérience : elle représente les sujets à faire vivre, animer et documenter pour se préparer à atteindre le premier des cinq niveaux de maturité de CMMI, qui est paradoxalement le niveau 2 (le niveau 1 indiquant une maturité non homogène des processus...

Principales caractéristiques de la documentation d’un projet informatique

Les projets mal documentés arrivent rarement à leur terme.

Une documentation pertinente, complète sans être obèse, assure une meilleure coordination entre les acteurs du projet, accélère l’intégration des nouveaux venus, diminue le risque de conflits, de déception et d’incompréhension des tenants et aboutissants du projet.

La documentation fait partie des livrables d’un projet, au même titre que son code.

D’ailleurs, au même titre que le code, la documentation doit être gérée en configuration (versionnée, structurée, etc.) et à jour. Les éléments de documentation qui ne seraient pas à jour doivent a minima être signalés comme obsolètes afin d’éviter toute confusion chez leurs lecteurs futurs. Pour gérer l’obsolescence des composants documentaires, vous pouvez, en première approximation, les attacher aux branches majeures gérées dans votre outil de gestion de configuration (Git, etc.).

Il est essentiel de documenter soigneusement les projets informatiques afin de garantir leur convergence à moyen terme, leur maintenabilité et leur évolutivité à long terme. La documentation permet de faciliter la compréhension et la modification...

Documentation des enjeux et des modes de gestion du projet

Dès la discussion sur l’opportunité d’un projet, les enjeux associés guident naturellement les débats autour de ce projet. Pour autant, la compréhension de ces enjeux évolue pendant le projet, il faut donc maintenir à jour cette information tout au long du processus et rappeler sous quelles hypothèses a été prise chaque décision.

Dans certaines organisations, toutes ces informations sont consignées dans un plan projet amendé régulièrement (qui peut être un site internet ou une application dédiée abritée par un framework comme Gitlab, Obsidian, etc.), partagé et connu de tous, référençant tous les autres documents du projet, que ce soit les tableaux de suivi d’avancement à jour ou les documents techniques.

Architecture globale du SI en relation avec le projet

L’architecture globale fournit un aperçu architectural de la solution, en représentant ses différents aspects à l’aide de différentes vues. Elle vise à capturer, éclairer et transmettre les décisions architecturales significatives prises ou à prendre.

L’architecture globale fournit une vue d’ensemble complète de l’architecture de la solution. Elle sert de moyen de communication entre le sponsor et les architectes concernant les points importants du projet. L’architecture globale est le document de référence des revues qui vérifieront la qualité de l’architecture dédiée au projet, aussi bien intrinsèquement qu’au regard des normes d’architecture de l’organisation.

Fiches de "Cas d’Utilisation Métier"

Ces fiches sont au centre de votre stratégie de recueil des exigences des futurs utilisateurs de votre application. Elles permettent d’établir un vocabulaire commun entre eux et vous.

Chaque cas d’utilisation métier doit être accompagné d’une description claire (vous pouvez fournir un schéma de cas d’utilisation UML).

Dans le cycle de gestion de projet agile, il est essentiel de gérer les « histoires » afin de fournir des « versions logicielles » englobant des « fonctionnalités ».

Un exemple typique d’histoire utilisateur (story) est le suivant : En tant que <type d’utilisateur>, je souhaite <…> afin de <…>.

Étant donné qu’un cas d’utilisation est plus détaillé qu’une histoire :

Documentation de la gestion des Problèmes et des Défauts

Un système de gestion des problèmes/défauts doit être en place.

Quand utiliser le formulaire ci-dessous :

Fiche de Problème/Anomalie

Release note (note décrivant le contenu d’une version livrée)

Chaque publication en test d’acceptation et/ou en production doit comporter une description claire et concise :

Documentation technique moderne des applications et des Systèmes d’Information

À la fin du projet ou d’une release majeure, vous devez livrer divers codes, scripts, etc., mais aussi une documentation explicite permettant de démarrer le cycle de maintenance de l’application. Cette documentation a été construite tout au long du projet et fait intrinsèquement partie du produit que vous livrez.

Aujourd’hui, la documentation technique à produire et à gérer au sein d’une organisation s’avère prendre la forme d’un « produit similaire à un code informatique » au même titre que les autres composants de l’application ou du SI. L’ensemble de ses composants est géré en configuration via des logiciels comme Git.

Idéalement, ses composants se concrétisent comme étant :