Alex: Je travaille à Obeo et je suis le principal contributeur de Mylyn Intent. Mais je passe la majorité de mon temps à développer Sirius le nouveau projet open source que l'on va sortir dans Eclipse, et principalement aussi sur la partie travail collaboratif pour faire un pont entre CDO et Sirius.
Alex: A la base, c'est un projet de Cédric (Brun), qui est assez fan de Donald Knuth, l'inventeur du Literate programming, nous aurons peut-être l'occasion d'en parler un peu plus tard. Il a eu cette idée de trouver une autre façon de définir les modèles, en passant par la documentation. En fait, on part d'un constat très simple, c'est que les modèles sont difficiles à décrire, qu'ils contiennent beaucoup d'informations complexes et que du coup, un éditeur arborescent ne permet pas de conserver tous les choix de conception qui ont poussé à définir le modèle tel qu'il est. Donc, c'est ça l'historique de la création du projet, c'était mon sujet de stage.
Donc Mylyn Intent est un environnement de documentation comme textile, sa particularité est qu'il va vous permettre pour n'importe quel élément du code de connaître la partie de la documentation qu'il faut mettre à jour. Parce qu'en fait on se rend compte que le principal problème que l'on a avec la documentation aujourd'hui c'est que très vite, elle ne va plus être à jour, ce qui va induire le lecteur en erreur, ce qui la rend inutile.
3. InfoQ: Tu parles de documentation synchronisée il me semble ?
Alex: Oui, documentation synchronisée, c'est-à-dire une documentation qui reflète bien les changements qu'on a fait dans le code et ne contient pas des aberrations.
Alex: Alors, déjà Mylyn ce n'est pas seulement de la gestion de tâches, le but de plus haut niveau du projet Mylyn est de traiter toutes les parties de l'ALM, l'Application Lifecyle Management, ça concerne tout le cycle de vie d'un logiciel. La gestion de tâches avec Mylyn Task est un sous-produit de Mylyn. On va également gérer la construction des projets, la documentation, qui est une partie importante du cycle de vie des logiciels. C'est pour cela que l'on est dans Mylyn au même titre que Textile qui est aussi un éditeur de documentation, est dans Mylyn Docs.
Alex: Alors d'abord, pour replacer le contexte, Donald Knuth est le papa de LaTeX, il est un grand amoureux de la documentation. On pourrait traduire le Literate par quelqu'un qui sait manier les mots. On pourrait dire Programmation Lettrée. Le principal concept du Literate Programming est de sortir de la programmation structurée où tous les concepts sont guidés par le code, et donc où il est très difficile de comprendre les choix de conception qui ont été fait juste en lisant le code. Donc l'idée du Literate Programming, c'est de remettre la documentation au centre du processus de développement, et en gros de définir nos programmes directement dans la documentation. L'idée est de s'adresser à des humains plutôt qu'à des ordinateurs, c'est ça l'idée du Literate Programming. On a un literate programme, qui est un mélange de bouts de documentation et de code qui correspondent. Au lieu d'écrire directement notre code, on va structurer notre code en fonction de la documentation, et non plus en fonction du paradigme du langage.
Alex: C'est ça, et ça permet de nous abstraire de la structure du code et de vraiment présenter le code dans l'ordre qui nous paraît être le plus simple pour que quelqu'un qui arrive dans le projet comprenne tout de suite ce que le code fait.
Alex: Spirituellement, on est très proche. On a le même but, mettre la documentation au centre, parce qu'on pense que c'est un très bon endroit pour capturer les choix de conception, les choix techniques, et ce sont des choses aussi importantes que le code, finalement quand on rentre dans un projet. Par contre on a quand même pas mal de différences avec le Literate Programming. Premièrement, dans l'original la documentation était en latex et le langage de programmation était le C. Alors que dans Intent on va être beaucoup plus générique, on va pouvoir mélanger de la documentation avec du code Java, du code C++, des modèles, des manifestes, et en plus c'est extensible donc on va pouvoir se synchroniser avec plein de types d'artefact. Et l'autre principale différence c'est que dans le Literate Programming, pour éditer le code, il fallait passer par le literate programme. C'était contraignant, parce qu'on ne pouvait pas utiliser l'éditeur de son choix pour éditer le code C.
Dans Intent, on va pouvoir éditer le code avec l'éditeur de son choix, le JDT pour Java ou un modeleur si ce sont des modèles. Le cycle de vie du code et la documentation sont complètement séparés. Vous pouvez si vous le souhaitez modifier le code sans mettre à jour la documentation. Intent va simplement mettre un marqueur qui dit attention vous avez probablement cette zone là de la documentation qui n'est plus à jour, vous pourrez la mettre à jour tout de suite ou plus tard.
Alex: Le problème dans Markdown, c'est que oui on peut mettre des extraits de code, mais derrière le code de notre logiciel va évoluer et il y a de fortes chances pour que nos extraits de code deviennent obsolètes et se désynchronisent au même titre que la documentation. Le problème est que ces extraits de code ne sont pas liés au vrai logiciel, donc ils vont finir par être faux aussi.
9. InfoQ: Tu as beaucoup parlé de documentation de code, peut-on documenter autre chose que du code ?
Alex: Le principe général d'Intent est de mélanger de la documentation avec des artefacts techniques. On suit une approche basée sur les modèles, donc du moment que l'on sait représenter un artefact technique, que ce soit une classe Java, une classe C++, un manifeste, une tâche sur Bugzilla, sous forme de modèle, en configurant un adaptateur dans Intent, on peut référencer cet artefact. On peut aussi référencer un livrable Hudson ou une version dans GIT, ou un schéma de base de donnée.
Alex: C'est une bonne question, ce qu'il va se passer dans Intent si tu références une classe qui n'existe pas, Intent va te le dire. Ce qui est déjà pas mal. Par contre, effectivement, on n'a pas encore d'assistance contextuelle qui va te proposer de créer l'artefact manquant. Je vais noter cette demande d'évolution ! Pour le moment, c'est vrai que l'on va plutôt créer d'abord la classe Java puis la référencer dans Intent, c'est peut-être même plus pratique que de taper le nom de la classe dans la documentation.
Alex: C'est tout simple, comme je l'ai déjà évoqué, dans Intent on a des références vers des artefacts techniques, quand je vais modifier ces artefacts techniques, il y a des écouteurs Intent qui vont détecter la modification, synchroniser la documentation, comparer le dernier état connu de l'artefact technique enregistré dans la doc avec le nouvel état de celui-ci. Si on trouve des différences il va lever des erreurs de synchronisation sur toutes les petites parties de documentation qui référencent cet artefact technique.
Alex: Oui, on est obligé de conserver une copie du contenu pour que quand on décide de corriger une erreur de synchronisation qui a lieu au bout de six mois on puisse comparer entre le code et la dernière fois que la documentation a été un jour.
Alex: En effet, c'est le comportement du pont Java par défaut, mais si ça ne te satisfait pas et si tu souhaites conserver uniquement la liste des méthodes, et bien tu peux brancher ton propre pont de synchronisation Java qui va représenter une classe Java avec un modèle beaucoup plus réduit, tu peux représenter la java comme tu l'entends.
15. InfoQ: Peut-on tout simplement référencer un autre élément de documentation ?
Alex: Oui c'est possible de faire ça, j'en ai pas parlé pendant mon exposé, il est possible de référencer un autre élément de documentation en utilisant la clause @ref. Par ailleurs, au moment où on va exporter la documentation on va prendre en compte tous les liens de documentation. Quand le lecteur va lire la version exportée en HTML, on proposera de lire telle ou telle section qui fait référence à la section en cours. L'idée étant guider le lecteur dans sa lecture.
Alex: Oui, alors déjà c'est extensible. Pour le code Java, on affiche pas tout le code, parce qu'on estime que ce serait trop lourd, on se contente d'afficher une petite icône avec l'emplacement de la classe Java, et si le lecteur souhaite visualiser le code, alors, il peut faire un contrôle click qui ouvre la classe Java. C'est nécessaire sinon l'éditeur finirait par être très gros.
Il est possible de plus d'étendre ce comportement, par exemple pour un exposé que l'on avait fait avec Goulwen (Lefur), le principal contributeur de EEF, proposait une nouvelle approche qui s'appelait le test guidé par la documentation, dans laquelle pour représenter les tests on utilisait une syntaxe Xtext. C'est complètement configurable.
Alex: Oui, Intent repose sur une architecture client serveur, avec un dépôt dans lequel on va stocker la documentation, cette notion de dépôt de documentation est complètement abstraite, tu peux choisir n'importe quelle technologie concrète pour l'implémenter. L'implémentation par défaut est assez basique, elle stocke la documentation comme un fichier XMI dans un dossier caché. Pour Kepler, on a travaillé sur une autre implémentation de dépôt basé sur CDO qui permet de partager des modèles en temps réel, et là, la documentation est stockée dans une base de données. Quand l'utilisateur enregistre sa documentation, les modifications sont reportées en temps réel sur les postes des autres utilisateurs. On va donc pouvoir partager sa documentation en temps réel et avoir des retours sur ce que l'on est en train d'écrire, ce qui peut être intéressant.
Alex: L'idée était de stocker la documentation sous forme de modèles, par ce que ce format nous apporte plein d'avantages, notamment le fait de pouvoir choisir la technologie de stockage, en particulier CDO, que l'on peut utiliser gratuitement et stocker dans une base de données. Le fait de ne pas à avoir à choisir une représentation textuelle permet d'être libre dans le choix de la façon dont on présente la documentation à l'utilisateur. Pour nous, la représentation textuelle, c'est juste un affichage du modèle, mais on peut tout à fait imaginer un autre éditeur qui afficherait la documentation sous forme graphique, par exemple le chapitrage. On veut vraiment s'abstraire de la syntaxe textuelle, c'est uniquement un outil que l'on offre à l'utilisateur mais ce n'est pas du tout ce que l'on veut stocker.
Par ailleurs, le fait de nous baser sur des modèles nous permet de bénéficier de toutes les technologies de modélisation Eclipse. En particulier, pour générer la documentation, nous utilisons Acceleo, du coup, c'est assez facile d'écrire son propre générateur Acceleo pour exporter la documentation en LaTeX, en HTML. En plus, Acceleo fournit un mécanisme d'héritage, qui permet de reprendre un générateur par défaut d'Intent, et de modifier uniquement un détail du générateur que l'on souhaite.
Alex: Oui en effet, en tout cas pour les parties de documentation pure. On a fait ce choix-là parce que Textile est basé sur l'analyseur de texte Wikitext, qui supporte pas mal de syntaxes de type markup, et puis, parce que Textile est très connu de la communauté Eclipse. Mais pour autant, c'est complètement générique, et on peut imaginer brancher un autre analyseur de texte, pour par exemple écrire du LaTeX à l'intérieur de notre documentation.
Alex: Oui, mais si on souhaite utiliser par exemple ASCII Doc, ce qui m'a déjà été demandé, il suffit d'écrire un analyseur de texte qui va transformer le format ASCII Doc vers le modèle interne Intent.
Alex: Pour le moment, pour la version 0.8 livrée avec Kepler, l'export Web utilise Bootstrap, ce qui rend la documentation un peu dynamique quand l'utilisateur passe sa souris sur une section : on va lui proposer des liens vers d'autres sections qui peuvent l'intéresser. Pour autant, je ne dirais pas que l'export Web est très mature, y a encore plein d'améliorations que l'on peut faire. Ce n'est pas notre priorité, on essaie déjà à ce que les gens écrivent de la documentation Intent, et ensuite, ils nous remonteront leurs besoins sur le rendu final. Pour ce qui est de l'export PDF, Cédric (Brun) est en train d'écrire un générateur Latex qui permettra de générer du PDF.
23. InfoQ: Vous passez par du latex pour générer le PDF ?
Alex: Oh, parce que latex, c'est ce qu'il y a de mieux pour générer un joli PDF !
Alex: Encore une fois, tu modifies le code autant que tu veux, on ne va pas toucher à la documentation, c'est toi qui sait ce qui est le mieux de faire. Donc, si tu refactores une classe, on va effectivement lever une erreur de synchronisation, mais c'est à toi de voir si c'est effectivement une erreur par rapport à ta spécification, et donc tu annules le refactoring, ou si effectivement, tu veux mettre à jour la documentation. On ne mettra jamais à jour la documentation à la place de l'utilisateur. C'est vraiment à l'utilisateur de le faire, on est juste là pour pointer les zones de documentation à mettre à jour.
Alex: Soit sur le site Web d'Intent, soit sur le wiki et vous aurez tous les liens qu'il faut, sur le bugzilla Eclipse, en dessous du composant Mylyn Docs.
26. InfoQ: Au fait, Mylyn Intent est disponible dès aujourd'hui ?
Alex: Oui bien sûr, on est aligné sur la sortie annuelle d'Eclipse, depuis l'année dernière. Intent 0.7 faisait déjà partie de Juno et cette année, on participe à Kepler. Intent est donc disponible soit sur le site de mise à jour de Kepler, soit sur le site de mises à jour d'Intent.