Blog ENI : Toute la veille numérique !
Accès illimité 24h/24 à tous nos livres & vidéos ! 
Découvrez la Bibliothèque Numérique ENI. Cliquez ici
Accès illimité 24h/24 à tous nos livres & vidéos ! 
Découvrez la Bibliothèque Numérique ENI. Cliquez ici
  1. Livres et vidéos
  2. Vade-mecum de l'informatique contemporaine
  3. mecum de l'informatique contemporaine
Extrait - Vade-mecum de l'informatique contemporaine (TCP, SOA, Linux, Python, Docker, HDFS, RDF, Adam, OWASP, KPI, UML, Scrum…)
Extraits du livre
Vade-mecum de l'informatique contemporaine (TCP, SOA, Linux, Python, Docker, HDFS, RDF, Adam, OWASP, KPI, UML, Scrum…)
1 avis
Revenir à la page d'achat du livre

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.

1. Besoins motivant la création du projet

Décrire l’origine des besoins préliminaires : changement de réglementation, dysfonctionnement existant, innovation, conclusions d’un audit, souhait ou nécessité de mettre en œuvre un changement, lancement d’un nouveau produit, refonte, mise à jour d’un produit (familles de produits, types de produits, modes de gestion des produits, etc.).

Plus loin dans la vie du projet, ces besoins présideront à la définition des exigences, des cas d’utilisation, ou des user stories gérées dans un cycle agile.

Décrivez les canaux de distribution et les objectifs marketing éventuels du projet.

2. Champ d’application et situation

Explorer le « pourquoi » du projet.

a. Définition du problème

Présenter une déclaration synthétisant le problème que ce projet vise à résoudre. Le format suivant peut être utilisé.

 

[décrire le problème]

concerne

[qui sont les parties prenantes affectées par le problème]

dont les conséquences sont

[quel est l’impact du problème]

une solution efficace permettrait de

[énumérer les principaux bénéfices d’une solution efficace]

b. Positionnement du produit ou de la solution

Décrire la position que le produit ou la solution...

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.

1. Personnalisation de l’architecture globale

Le plan de l’architecture globale peut être adapté en fonction de la nature du projet. Certaines sections peuvent être considérées comme non pertinentes ou raccourcies. Certains aspects spécifiques peuvent nécessiter leur propre section supplémentaire. Des annexes doivent être ajoutées pour expliquer certains aspects.

2. Portée de l’architecture globale

Décrivez à quoi s’applique votre architecture globale :

  • Quels sont les besoins couverts ? Quels sont les principaux processus/activités et parties prenantes impliqués ? Y a-t-il des liens avec d’autres domaines, des partenaires commerciaux, des clients finaux ou des systèmes externes ?

  • Quelles applications le projet crée-t-il, remplace-t-il ou modifie-t-il ? Sont-elles des applications internes, B2B (Business to Business), B2C (Business to Consumer) ?

  • Le projet est-il l’occasion de construire un nouveau cadre architectural ou une nouvelle infrastructure ?

  • Y a-t-il des prérequis pour le projet ou des liens avec d’autres projets ? Le projet peut-il être désynchronisé des autres projets ?

  • S’agit-il d’un projet d’urgence, d’un projet classique ?

  • Qu’est-ce que le projet ou la solution ne fait pas ? (Le dire explicitement). Quels éléments sont exclus du projet ?

  • La solution envisagée est-elle...

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 <…>.

Les exigences, les modèles UML, les modèles d’architecture (comme dans TOGAF) et les fonctionnalités sont interconnectés et souvent liés aux histoires et aux cas d’utilisation. Cependant, leurs descriptions ne sont pas toujours exhaustives et formalisées. À l’inverse, les histoires et les cas d’utilisation ont une définition sémantique claire.

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

  • Certaines histoires sont complétées par le propriétaire...

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 :

  • Si vous n’utilisez pas de gestionnaire de problèmes intégré ou si vous souhaitez gérer en détail les problèmes, vous pouvez utiliser un tel formulaire. Ce formulaire de défaut n’est pas nécessaire si un outil de test est utilisé, car l’outil permet la gestion des formulaires et des listes de défauts.

  • Ce formulaire est un moyen par lequel les équipes peuvent communiquer chaque fois qu’il est nécessaire de décrire des éléments complémentaires pour un défaut donné. Il n’est pas obligatoire pour tous les défauts.

Fiche de Problème/Anomalie

Champ

Description du champ

Commentaires et exemples

0 - En-tête

Projet

Désignation du projet/sous-projet ou du portefeuille d’applications, ainsi que le code du projet ou du portefeuille d’applications définissant le périmètre dans lequel le formulaire de défaut est applicable. Ce champ est obligatoire lors de la configuration du défaut.

 

1 - Identification

Description succincte

Brève identification du défaut. Ce champ est obligatoire lors de la configuration du défaut.

 

Identifiant du défaut

Il s’agit de l’identifiant du défaut, identique à celui de la liste des défauts. Ce champ est obligatoire lors de la configuration du défaut.

 

Référence de suivi

Correspond à l’identifiant utilisé comme référence pour le suivi du traitement du défaut par un tiers ou un outil spécifique. Si la liste des défauts et les formulaires sont gérés manuellement, cette référence peut être identique à l’identifiant du défaut.

 

Sujet ou thème

Cette information...

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 :

  • une synthèse des objectifs globaux de la release ;

  • le périmètre global de la publication ;

  • les licences et droits associés à la version et à ses composants ;

  • une liste de références [cette sous-section fournit une liste complète de tous les documents référencés avec un statut clair : document à jour ou pas] ;

  • aperçu [cette sous-section décrit ce que contiennent le reste des notes de version et explique comment le document est organisé] ;

  • fonctionnalités incluses dans la release [une description fonctionnelle, comprenant les caractéristiques ou fonctionnalités définissant la version] ;

  • produits compatibles, ce produit a été testé sur les plateformes ou avec les produits suivants :

  • [Listez les produits ou plateformes],

  • [Listez les exigences de l’environnement opérationnel].

  • techniques de mise à niveau [décrivez le processus de mise à niveau à partir des versions précédentes du produit, référencez les scripts et outils d’installation et/ou mise à niveau] ;

  • nouvelles fonctionnalités...

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 :

  • des composants purement documentaires (on ne peut pas faire moins !) :

  • un corpus de documents en markdown ou similaire (quarto.org, Rmarkdown Obsidian, etc.) qui utilisent les autres composants ;

  • les codes de modèles graphiques (UML, C4, Archimate, etc.) permettant de régénérer les graphiques à inclure dans la documentation (par exemple : du code plantUML, Mermaid ou GraphviZ, etc.) ;

  • des fichiers graphiques SVG éventuels (quand vous êtes contraint de dessiner plutôt que de générer vos graphiques, dessinez en SVG) ;

  • d’éventuelles copies d’écrans de l’application en .png (l’utilisation d’un logiciel pour décrire les wireframes, à savoir les schémas des interfaces homme-machine (les écrans) s’avère être une excellente idée) ;

  • les fichiers de bibliographie (au format .bib) décrivant...