Format de documentation d’un projet TI; meilleures pratiques

Voir la version AMP

Quel est le format de documentation d’un projet TI le plus approprié ?  Et, quelles sont les meilleures pratiques de documentation d’un projet TI en termes de format ?

La question peut paraître étrange car pour plusieurs, cette question ne se pose même pas. Mais en y regardant de plus près, elle mérite qu’on s’y attarde; comment doit-on documenter un projet TI et avec quel type de format ?

Pour mettre en lumière le défi du format de documentation, il faut tenir compte de trois facteurs :

  • Objet de la documentation
  • À qui elle s’adresse ?
  • Par qui est-elle produite ?

Quel est le format de documentation d’un projet TI le plus approprié et quelles sont les meilleures pratiques de documentation ?

Répondre à cette question n’est pas si simple car sans être infinis, les formats de documentation potentiels sont nombreux :

  • Fichier Word
  • Fichier Excel
  • Fichier Visio
  • Fichier Enterprise Architect
  • Fichier RTF
  • Fichier Markdown
  • Fichier Balsamic Mockup

Chez Analystik, nous utilisons tous ces différents formats, voici pourquoi.

 

Fichier Word et Excel

Certains documents doivent être partagés avec les clients, c’est le cas, par exemple, des comptes-rendus de réunion, des requis et de la documentation fonctionnelle.  Nous utilisons donc pour ces documents un format accessible par tous; Word.

Quant au format Excel, nous l’utilisons systématiquement pour compiler les « to-dos » suite à une réunion et pour des cas particuliers comme la définition et la documentation fonctionnelle d’un algorithme complexe.

 

Fichier Visio

Malgré le fait que les capacités du logiciel Enterprise Architect sont plus évolués, nous avons décidé chez Analystik d’utiliser Visio pour sa simplicité et sa plus grande diffusion.  Nous l’utilisons pour schématiser des processus et pour créer nos diagrammes UML.

 

Fichier Markdown

Pour la documentation technique qui implique généralement l’ensemble de l’équipe de développement, nous sommes passé du format RTF au format Markdown car ce format est de plus en plus standard et les éditeurs sont de plus en plus performants.  Les avantages de ce dernier est le versionning (l’outil d’édition conserve l’historique des versions) qu’il procure et la comparaison des versions.

Ces deux formats, utilisés à l’intérieur d’un environnement de développement comme Team Foundation Server (Team Service), gèrent bien les check-in & check-out et permettent donc une édition facile par de multiples usagers.

 

Fichier Balsamic Mockup

Dans le cas de Balsamic, je dirais que c’est une histoire d’amour chez Analystik.  Il fait une seule chose mais il la fait tellement bien et tellement facilement.  Il nous permet de faire les maquettes d’écran qui seront incluses dans notre documentation fonctionnelle.

 

CONCLUSION

Dans ce billet, nous avons décrit comment nous documentons chez Analystik.  Dans notre prochain billet, le troisième et dernier de la série, nous parlerons de la façon dont nous sauvegardons toute cette information.

 

Bon projet de Développement,

 

Denis Paul & Michel

Laisser un commentaire

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