L’architecture Agile et la documentation.. Est-ce possible ?

Like This!

Add to FacebookAdd to DiggAdd to Del.icio.usAdd to StumbleuponAdd to RedditAdd to BlinklistAdd to TwitterAdd to TechnoratiAdd to Yahoo BuzzAdd to Newsvine

1. Introduction

Souvent lorsque nous parlons des Méthodologies Agiles,
l’un des premiers éléments qui sont souvent cités. C’est qu’on ne fait pas de
documentation. Pourtant on doit en faire, c’est nécessaire. Je vous ai donné
les premières bases de la documentation ici dans cet article On documente quoi et comment.

Mais, lorsqu’on réussit à convaincre les gens, que la
documentation est nécessaire. Il y a encore trop souvent, une de ces grandes
parties délaissées de la documentation. C’est bien la documentation de
l’architecture. Pourtant, c’est la base de notre logiciel.

Soyez prévenu, choisir de documenter son architecture. Ce
n’est pas un choix facile. Car, il y a plusieurs approches. Mais, la seule et
unique règle que nous vous recommandons, c’est la simplicité et l’efficacité
doit primer sur tout le reste.

De plus, peu importe votre choix d’outils pour documenter
votre architecture, c’est très important. Il doit produire une documentation
vivante et partageable facilement.  Et pourquoi pas, être écologique en
priorisant une solution électronique de vos documents.

2. Pourquoi documenter l’architecture, c’est bien qu’une question de choix

La phase de l’architecture de notre logiciel est l’une des
plus importantes, tout au long de notre processus de développement logiciel.
Elle a pour but d’apporter la vision tant sur le travail à accomplir que sûre
qu’ont les orientations possibles de notre logiciel.

Mais la meilleure manière de partager et de présenter cette
vision, surtout au-delà de la période  de développement. C’est faire de la
documentation de l’architecture, et peu importe le format, elle sert essentiellement
à communiquer durant le développement aux membres de votre équipe qui mettront
en œuvre cette vision.

L’autre point important pour lequel nous faisons de la
documentation, c’est pour la partie d’entretiens du cycle de vie de notre
logiciel. Un logiciel en moyen passera entre 75%-80% du temps en mode
entretien. Souvent, l’équipe qui fera cet entretien sera différente de celle
qui l’aura développé. Donc, il risque fort qu’il n’ait plus personne pour
raconter l’histoire des décisions qu’on a prises dans les différents travaux
d’architecture et d’analyse.

C’est facile de voir un beau modèle objet ou de données,
qu’en on la personne qui l’a conçu pour l’expliquer. Mais, imaginer que la
personne n’est plus dans l’organisation pour expliquer ces choix. Il peut
arriver que certains morceaux soient plus difficiles à comprendre.

En fin compte, faire ou non, la documentation c’est bien
une question de choix, de choix sur le comment on va la faire. Mais aussi,
jusqu’à où on va la documenter.

2.1. Juste assez, juste nécessaire

La règle qui régit ma pratique est juste assez pour la
compréhension des équipes qui vont nous suivre. Mais aussi nécessaire à garder
l’historique ou l’histoire de décisions qui ont été prises dans les différentes
étapes de la conception. La responsabilité de l’architecture, c’est de trouver
des solutions, avant qu’ils ne surviennent !

Autrement dit, ce qui est nécessaire pour comprendre le
processus décisionnel et le résultat obtenu. Donnez aux équipes l’information
qui leur sera utile pour continuer à maintenir ce que vous et votre équipe a
mis en œuvre. Il faut répondre  au pourquoi et comment on prit cette décision.

3. La documentation de la modélisation, UML pourquoi ou pourquoi pas!

L’un des outils qui sont souvent utilisés en modélisation,
c’est bien UML. C’est un excellent outil pour présenter la modélisation tant
objet que donnée.

Mais parfois, cette forme de modélisation n’est pas
toujours accessible à tout le monde. Elle est plus destinée aux personnes plus
techniques. Pour ma part, je l’utilise pour discuter avec les programmeurs ou
autres gens techniques.

Apprendre UML, malgré qu’une la connaissance peut
s’apprendre dans les livres ou assit dans une classe de formation. Il reste
toujours que le reste de la connaissance s’apprend uniquement par l’expérience.

Donc, malgré les nombreuses qualités d’UML, et je suis
loin d’en faire le procès ici, il ne correspond pas à tous les besoins et n’est
pas destiné à tout le monde.

A titre d’exemple, un diagramme de classe pour expliquer
le contenue d’un logiciel à client qui ne connait pas la modélisation objet, je
ne suis pas sur qu’il va comprendre quelque chose.

Il faut donc trouver un outil, un langage que toutes les
personnes impliquer dans la discussion vont comprendre. Et au besoin, pourquoi
pas d’inventer votre en cas de besoin.  Dessiner vos propres diagrammes, un
formalisme que tous les gens vont comprendre.

Et bien sûr, server aussi d’UML avec les gens qui le
comprennent ou encore si c’est plus facile pour vous. Mais, n’oubliez pas
l’objectif c’est de communiquer et de partager

4. Une documentation plus écrite ou en mode texte

Le premier réflexe que plusieurs personnes quand on parle
de documentation. C’est d’ouvrir un traitement de texte  (Genre Microsoft
Word). Mais, parfois, écrire un texte  pour tout détailler. Ça ne correspond
pas au besoin que vous devez combler.

Certaines choses se décrivent bien dans un texte. Mais
d’autres pas. Il faut savoir quand et comment, il faut  le faire dans un texte
ou avec un autre moyen.

De plus, il ne faut pas oublier que la plupart du temps,
un texte est un complément aux autres composantes qui documentent l’application.
Donc, il ne faut pas chercher à tout écrire ce qui est déjà dit d’une autre
manière  dans un autre outil.

J’ai trop souvent vu que les gens écrivaient en mode texte
un cas d’utilisation ou autre chose qui se décrivait par lui-même. Plus tôt, se
limiter que simplement décrire les cas limites ou l’interaction avec d’autres
cas.

Fixer la limite du texte ou de sa portée n’est pas une
chose facile, certaines règles s’appliquent. Mais c’est aussi un peu un art et
une science.

4.1 L’art et la science de la documentation.

Savoir limiter la portée d’un texte est  tant un art
qu’une science. Mais, de manière simple, je dis souvent d’écrire en mode texte
ce qui n’est pas évident au premier regarde des autres composantes de
documentations. Surtout si vous n’êtes pas là pour donner les explications
manquantes. Dans le cas contraire, ajouté du texte qui permettra à votre
lecteur de bien comprendre.

Un petit truc de métier, lorsque je ne suis pas sur de la
facilité de la compréhension. Je présente le diagramme ou le texte à une
personne qui n’a pas ma connaissance et je lui demande de m’expliquer ce qu’il
comprend. Généralement, je limite ce petit exercice à 3-5 minutes pas plus.
S’il n’est pas capable de m’expliquer, c’est qu’il manque de l’information ou
encore que mon diagramme est trop complexe.

5. Conclusion

En conclusion, faire la documentation de l’architecture
d’un logiciel ce n’est pas une chose facile à bien faire. Mais, ce n’est pas
pour autant qu’il ne faut pas la faire.

C’est  un défi qu’il faut relever. Car, un logiciel et son
architecture aura une vie beaucoup plus longue qu’on peut l’imaginer lors de sa
conception. C’est donc la documentation qui l’un de ces maillons qui, je crois,
vous permettra de rendre agréable toute la vie de votre logiciel. Tant durant
son développement que durant son entretien.

Il ne vous reste plus qu’à trouver  votre besoin en
documentation et comment le combler!.

  1. novembre 23, 2011 à 11:56

    Penser au lecteur ! La documentation est un moyen de communication, pas autre chose (quelque fois un support de réflexion, mais à ce moment-là il faut bien réfléchir à ce qu’on veut en conserver pour l’extérieur).
    Excellent article !

    Sur le même sujet, je recommande de lire mon article sur le point de vue du développeur qui va avoir à utiliser un n-ième document dans le cadre de son travail. Voir « L’endroit qui vous rend fou » https://ogourment.wordpress.com/2011/11/17/the-place-that-drives-you-ma/

    • novembre 23, 2011 à 12:11

      MERCI M. Olivier, le client est au coeur de tout développement logiciel. C’est donc normale que cette documentation soit orienté aussi pour lui !

  2. novembre 23, 2011 à 12:07

    J’ai oublié de dire que le document d’architecture prend naturellement sa place dans un wiki ou sharepoint corporatif … afin de pouvoir être consulté et maintenu le plus facilement possible !

    • novembre 23, 2011 à 12:13

      Le but de ce billet étant d’apporter une réflexion sur la nécessité de faire la documentation d’une architecture en mode agile. Et non sur les moyens de la faire.

      Mais, vous avez raison, les WIKI, les Sharepoint de ce mode sont des bons outils pour le faire et comme je disais, ils sont écologiques et vivant !

  3. Jean Lalande
    janvier 26, 2012 à 12:09

    Excellents articles Bruno et Olivier. Pour ma part, j’ai toujours pensé qu’un « point form » valait milles mots et qu’un diagramme valait milles point forms. J’ai travaillé longtemps dans une organisation qui avait tellement d’informations disponible que c’en était devenu un fouillis total, j’avais baptisé ça ‘Information Overload’. De nos jours, les équipes de soutien sont tellement débordés qu’ils n’ont pas toujours le temps de faire les recherches nécessaires. D’où la nécessité de trouver un bon équilibre dans la documentation, de bien la structurer et surtout, éviter les romans.

  4. janvier 26, 2012 à 12:45

    MERCI M. Jean Lalonde pour votre commentaire.

    Ne vous en faites pas, j’ai travaillé aussi souvent pour des organisations qui produisaient trop documentation et surtout qu’elles ne comprenaient pas pourquoi elles la produisaient.

    Lorsqu’on documente, il savoir pourquoi et comment on le fait !

  5. Alain Cardinal
    janvier 15, 2013 à 7:54

    J’enseigne l’architecture à l’ÉTS, je suis d’accord au niveau de la documentation, c’est vraiment un art de bien documenter, mais en bout de piste l’important reste à qui on s’adresse.

    • janvier 22, 2013 à 7:17

      Merci M. Alain Cardinal, j’aurais voulu trouver une phrase qui résume bien mon article. Je n’aurais pas fait mieux !

  1. No trackbacks yet.

Répondre

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion /  Changer )

Photo Google

Vous commentez à l'aide de votre compte Google. Déconnexion /  Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion /  Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion /  Changer )

Connexion à %s

%d blogueurs aiment cette page :