• 8 heures
  • Moyenne

Ce cours est visible gratuitement en ligne.

course.header.alt.is_video

course.header.alt.is_certifying

J'ai tout compris !

Mis à jour le 04/01/2021

Documentez pour mieux communiquer

Connectez-vous ou inscrivez-vous gratuitement pour bénéficier de toutes les fonctionnalités de ce cours !

Appréhendez le coût d'une mauvaise planification

Dans la vidéo ci-dessus, vous avez découvert l'erreur de planification historique du Bradley Fighting Vehicle (BFV) du gouvernement américain. Bien qu'il ait finalement été construit selon les besoins exprimés par le gouvernement et qu'il ait très bien servi l'armée américaine, son développement a été un cas classique de mauvaise gestion bureaucratique, prenant 17 ans à l'armée et coûtant 15 milliards de dollars aux contribuables américains. Cette erreur de planification extraordinaire était le résultat de besoins mal documentés et mal définis et d'un manque de compréhension du coût élevé qu’entraîne la correction d’erreurs à un stade avancé d’un projet. La réponse fournie par l’armée lorsque des préoccupations étaient soulevées concernant ces erreurs était  "nous allons corriger cela en production".

Si des erreurs dans la documentation ne sont pas détectées et corrigées dès les premières étapes de la planification, elles se manifesteront au cours de l'élaboration, et il sera alors beaucoup plus coûteux de les corriger. Plus une erreur est découverte tard, plus son coût de correction sera élevé.

L’importance de ce coût dépend du modèle de développement de projet utilisé.

Graphique représentant le coût du changement selon 3 méthodologies : en cascade, agile idéalisée et agile
Le coût du changement en fonction des différentes phases d'un projet

Le graphique ci-dessus montre le coût des changements à apporter au cours de l'élaboration du projet selon trois modèles de gestion de projet différents : en cascade, agile, et agile idéalisé.

Qu'est-ce que ce graphique veut dire, exactement ?

Analysons-le ensemble !

Les modèles de gestion en cascade

Les modèles de gestion de projet en cascade, tels que Six Sigma et le cycle de développement logiciel (SDLC), sont les modèles les moins chers et les plus faciles à utiliser pour effectuer les premiers changements, par exemple pendant les phases de recueil des besoins et de conception du projet. Mais le coût d'un changement devient rapidement incontrôlable une fois que le développement commence.

Au moment où vous arrivez en production, vos coûts pour un changement sont jusqu'à 1 000 fois plus élevés que si vous aviez effectué le même changement avant la phase de développement. Un changement au cours d’une phase ultérieure à la phase de développement exige que toutes les phases précédentes soient complètement refaites, ce qui est non seulement coûteux, mais également frustrant pour les gestionnaires de projet et les développeurs.

Le modèle "agile idéalisé"

Le modèle "agile idéalisé" n'est pas tout à fait un modèle réel, mais un modèle hypothétique dans lequel eXtreme Programming (XP), un type de développement agile, est utilisé conjointement avec une approche de conception pilotée par les tests (TDD). En théorie, cette méthode réduit la boucle de rétroaction à quelques minutes au lieu de plusieurs jours, semaines ou mois, ce que l'on observe habituellement dans les processus en cascade. Par conséquent, le coût du changement ne sera probablement jamais hors de contrôle.

Cependant, puisqu'un modèle agile idéalisé est, comme son nom l’indique, « idéalisé », nous pouvons supposer qu'il est peu probable qu'il soit réalisé dans la pratique. Il y a en effet tout simplement trop de variables supplémentaires qui ne peuvent être contrôlées, mais qui auront une incidence sur la courbe du coût du changement.

Le modèle agile

La ligne violette du graphique représente une courbe de coût de changement beaucoup plus appropriée que celle que qu’on trouve généralement pour les projets de développement agile. La courbe ne s'aplatit pas ; au contraire, elle monte doucement avec le temps et tout au long du cycle de vie du projet. Le fait qu'elle s'élève n'est pas surprenant et ne devrait pas non plus être une source d'inquiétude. C'est simplement le résultat de la progression du développement d'un projet.

Par exemple :

  • la base de code d'un projet augmente avec le temps. L'augmentation du nombre de lignes de code augmente la probabilité qu'une modification touche d'autres parties du code, ce qui augmente le coût de la modification en fonction de la croissance du nombre de lignes de code ;

  • en plus de l'augmentation de la base de code au fil du temps, le nombre d'artefacts non codés augmentera également. Il s'agit notamment de documentation, de modèles, de diagrammes, etc. Plus le nombre de ces artefacts non codés augmente, plus le coût d'un changement augmente car il devra être répercuté partout. Une approche agile réduit le coût de tels changements, mais ne peut jamais les éliminer complètement ;

  • il est également possible que le processus utilisé ne soit pas parfaitement agile. Les équipes de développement agile tentent souvent de travailler dans des environnements très peu agiles. Les entités de gestion non agile peuvent imposer une variété de politiques et de procédures coûteuses, telles que de longues règles de documentation, des normes de codage auxquelles le travail des développeurs doit se conformer ou encore des examens techniques répétés, ce qui augmente considérablement les coûts totaux.

En travaillant avec une méthodologie agile, l'objectif est de créer une documentation de grande valeur. Cela signifie que vous créez beaucoup moins de documentation qu'un modèle traditionnel pourrait en avoir besoin, mais que votre documentation est plus directe et d'une plus grande utilité pour les personnes qui la liront. En éliminant les procédures inutiles dans la planification des projets, il est possible de réagir plus rapidement aux changements, simplement parce qu'il y a moins de travail à faire.

Une planification et une modélisation appropriées de votre projet sont essentielles pour aplatir votre courbe de coût du changement. Vous ne pouvez pas l'aplatir complètement, mais plus vous validez tôt vos artefacts de développement dans le processus, plus la courbe de coût du changement sera plate.

Découvrez à quoi sert la documentation

La documentation est une partie critique de tout projet de développement. Elle est souvent considérée comme une tâche redoutée par les chefs de projet et les développeurs. Mais quand nous parlons de documentation, nous ne parlons pas d'un ensemble ou d'une collection de guides de référence ou de manuels d'instructions méticuleusement écrits. Il s'agit d'un moyen de communiquer des informations importantes de la manière la plus claire possible à un public spécifique.

Nous écrivons donc de la documentation pour communiquer !

Mais, est-ce que ce n’est pas trop simple comme raison ? 

Je vous l’accorde, c'est peut-être une réponse trop simple. Regardons pour quelles raisons produire de la documentation.

Informer les intervenants

Vos intervenants ont demandé une documentation. La production de la documentation est fondamentalement une décision business : vous investissez les ressources des parties prenantes de votre projet dans l'élaboration de la documentation. C'est donc à elles qu'il revient de décider en dernier ressort si leur argent doit être dépensé de cette façon. 

Définir l'interaction entre plusieurs systèmes

C'est ce qu'on appelle généralement un contrat. Les contrats sont souvent nécessaires lorsqu'un groupe externe contrôle une ressource d'information dont votre système a besoin, telle qu'une base de données. L'élaboration d'un contrat devrait quand même être vérifiée par les intervenants de votre projet. Puisque vous dépensez leur argent, ils devraient avoir leur mot à dire sur la façon dont cet argent est dépensé et sur quoi. 

Faciliter la communication entre les équipes distantes

De nombreux projets sont aujourd'hui réalisés par plusieurs équipes sans tenir compte de l'emplacement géographique. Une équipe en Inde pourrait travailler avec une équipe en France et une équipe aux États-Unis sur le même projet. La documentation partagée est souvent un excellent moyen de faciliter la communication entre les différentes équipes.

Soutenir le développement agile

Avec un développement agile, il est important de préparer la prochaine itération (ou Sprint) tout en finissant celle en cours. Lors de l'élaboration d'un logiciel de travail, il est nécessaire d'élaborer de la  documentation pour l'utilisation et la maintenance du produit.

Préparer des audits de projets et/ou de systèmes

Certains systèmes doivent faire l'objet d'une vérification de sécurité ou de conformité aux réglementations des organismes gouvernementaux ou à certaines normes de l'entreprise dans laquelle ils seront implémentés. Dans ce genre de cas, des processus particuliers doivent généralement être mis en place et nécessitent une documentation indiquant comment le processus a été suivi.

Pour son propre bénéfice

Je pense... J'écris souvent de la documentation pour mon propre bénéfice. Je suis peut-être en train de réfléchir à un problème complexe. Documenter les processus m'aide à garder mes pensées organisées et me permet de changer facilement d'orientation ou de modifier mes plans d'action. Le simple fait de mettre vos idées sur papier – ou sur un écran, selon le cas – vous aidera très souvent à résoudre tout problème dans votre réflexion ou à confirmer le bien-fondé de votre décision. 

Il y a de nombreuses raisons pour lesquelles on pourrait vous demander de créer une documentation, mais quelle que soit la raison spécifique, il n'y a toujours qu'une seule raison qui motive la demande : certaines idées doivent être communiquées.

Facilitez la communication par la documentation

OK… Maintenant je sais pourquoi écrire de la documentation. Mais concrètement, comment je fais pour communiquer clairement mes idées ?

Eh bien, faites le test et tapez “Principes d’une communication écrite efficace” dans votre moteur de recherche. Vous obtiendrez une grande variété de résultats tels que :

  • les principes d’une communication efficace ;

  • 4 règles pour un travail écrit efficace ;

  • les techniques de communication écrite ; 

  • connaître les bases de la communication professionnelle.

Dois-je continuer ? Combien y a-t-il de "principes" de communication efficace ou de rédaction efficace ? Il n'existe aucun ensemble de principes ou de règles concrètes pour une rédaction efficace. Il y a des lignes directrices générales, mais quand on commence à les préciser, tout le monde a une opinion.

Mais alors, comment faire pour écrire une documentation efficace ?

Voici quelques conseils que je garde à l’esprit quand j’écris de la documentation.

Écrivez dans un but clair

Identifiez ce but et mettez-le en place. Ni vous ni moi ne voulons perdre notre temps avec de la documentation inutile, alors assurez-vous de bien comprendre pourquoi vous écrivez avant de commencer.

Écrivez clairement

Je suis passionné par les jeux de mots présents dans certaines pièces de théâtre, mais la documentation technique n'est pas l'endroit idéal pour tester vos talents d’écrivains. Si vous écrivez dans un but précis, utilisez des mots et des expressions qui amènent le lecteur directement à ce but.

Soyez attentif à votre public.

Une fois, je suis entré dans un cours sur les algorithmes complexes et les structures de données. L’assistant de l’enseignant a commencé le cours en présentant les composants de base d’un PC. L’enseignant avait mélangé les cours entre ses deux assistants et les avait envoyés dans la mauvaise salle de classe. Imaginez la tête des étudiants ! Tout ça pour dire que si vous ne comprenez pas votre public, ce que vous écrivez ne sera pas efficace. Avoir une idée précise de ce que votre lecteur doit retenir de votre documentation pourra vous guider lors de la rédaction.

Utilisez l'humour avec prudence.

J'aime utiliser l'humour lorsque j’écris. Ça m'amuse beaucoup. Si je me divertis pendant que j'écris, il y a de fortes chances que le lecteur soit aussi diverti, et un lecteur diverti est un lecteur attentif. Cependant, assurez-vous d'utiliser l'humour seulement si et quand vous le jugez approprié, et dans le contexte du document que vous êtes en train de rédiger.

Une documentation telle qu'un cahier des charges fonctionnel est, à bien des égards, beaucoup plus simple et moins exigeante que bien d'autres types d’écrits. Il n'y a pas de pression pour être trop créatif, original ou pour trouver des moyens de divertir votre public. Votre but est d'écrire aussi clairement et directement que possible. Mais cela ne veut pas dire que c'est facile. La rédaction de tels documents exige de la pratique et de l'ingéniosité.

En résumé

Voici un résumé de ce que nous avons vu dans ce chapitre :

  • une bonne planification est essentielle à la réussite d'un projet ;

  • les méthodologies agiles peuvent aplatir la courbe du coût du changement ;

  • l'objectif premier de toute documentation est la communication ;

  • vous trouverez partout des conseils pour écrire efficacement, et prendre le temps de les examiner et de les mettre en pratique dans vos écrits en vaut toujours la peine.

Dans le chapitre suivant, nous verrons plus en détail les méthodologies agiles, comment les utiliser pour documenter vos projets, et comment rendre votre documentation plus efficace en suivant quelques règles pour les rédacteurs techniques.

Exemple de certificat de réussite
Exemple de certificat de réussite