Note : Ce contenu a été créé avant que Fabernovel ne fasse partie du groupe EY, le 5 juillet 2022.

‍

Nous avons également commencé la réalisation des visuels de l’application :

• Les wireframes : les interfaces de l’application en noir et blanc situant les actions et les fonctionnalités ;
• Les maquettes : les interfaces finales de l’application respectant la charte graphique_._

Néanmoins, ces éléments graphiques ne permettent pas d’expliquer complètement comment l’application va se comporter à tout moment. Ils sont également sujets à interprétation par les développeurs. Dans la maquette ci-dessus, l’indicateur “0/10” peut être interprété comme un bouton, or il s’agit simplement d’un indicateur visuel montrant qu’aucun exercice de la séance n’a encore été réalisé.

#1 - Compléter les maquettes

Dans notre exemple, pour afficher des programmes contenant des exercices personnalisés, il faut prendre en compte les spécificités physiologiques et les contre-indications médicales propres à chaque adhérent.

Au delà des éléments graphiques en cours de réalisation, un certain nombre de questions se posent :

• Qui est l’utilisateur final de l’application mobile ? Un adhérent ? Un coach ?
• D’où proviennent les informations et les paramètres des exercices à afficher à l’utilisateur ?
• Comment filtrer les exercices du programme en fonction des spécificités physiologiques et médicales de l’utilisateur ?

Les wireframes et les maquettes ne contiennent pas les réponses à ces questions.

Ce sont alors les spécifications fonctionnelles et techniques qui complètent les éléments graphiques.

Dans tout projet de développement d’application (et de développement de logiciel au sens large), les spécifications vont permettre :

1. De déterminer une base commune de discussion avec l’ensemble des parties prenantes du projet : la définition d’un vocabulaire transverse ;
2. De décrire les règles métiers : les règles fonctionnelles qui régissent l’affichage des informations dans l’application et décrivent certains parcours ou cas d’usage (cas d’erreur, vues vides, etc.) ;
3. D’identifier les webservices : comment le serveur qui contient les données et l’application communiquent.

Cela peut paraître redondant, mais un projet non spécifié est un projet risqué. Tous les “savoirs” sont détenus par les acteurs historiques du projet, soit les personnes présentes lorsque tel ou tel point technique ou fonctionnel a été discuté. En cas de départ de l’un d’eux et sans spécifications, d’expérience, le projet a tendance à se détériorer. La communication se fait plus difficilement, certaines fonctionnalités ne sont documentées nulle part et personne ne sait comment elles fonctionnent.

Et sans attendre le départ de quelqu’un, ne rien écrire peut conduire à une situation où chacun a compris quelque chose de différent et où l’équipe finit par développer des fonctionnalités dont personne n’a voulues.

Des spécifications intelligibles et partagées avec toutes les parties prenantes du projet sont donc nécessaires et constituent la base de tout produit mobile. Il en va de la pérennité et de la maintenabilité de tout projet.

#2 - Partager une même compréhension des choses

Chez FABERNOVEL TECHNOLOGIES, nous avons mis en place des spécifications fonctionnelles sous la forme d’un document spreadsheet partagé. C’est LE document de référence entre toutes les parties prenantes du projet.

Ce document détaille :

• Les fonctionnalités_ (appelées aussi User Stories)_ à développer : un ensemble d’actions qu’un utilisateur peut réaliser via l’interface pour atteindre un objectif (consulter, éditer, supprimer des informations, etc.).
• L’ensemble des scenarii exhaustifs qui y sont rattachées : les étapes et les variantes possibles dans la réalisation de cet objectif (utilisateur connecté versus utilisateur non connecté, etc.).

Le document de spécifications définit aussi le vocabulaire du projet où l’on retrouve les définitions des objets majeurs manipulés dans toute l’application.

Dans notre exemple, le document définit :

• Un utilisateur : un adhérent à la salle de sport
• Un coach : la personne qui va conseiller l’adhérent dans ses entraînements
• Un programme d'entraînement : des séances contenant des exercices personnalisés et filtrés par adhérent. etc.

#3 - Faire face à tous les cas possibles

Les spécifications permettent donc de décrire toutes les règles métiers de l’application, c’est-à-dire ce qui contraint l’affichage d’informations.

Pour reprendre notre exemple, le fait d’afficher des exercices filtrés suivant les caractéristiques physiologiques ou contraintes médicales de l’utilisateur correspond à une règle métier. Cette règle métier requiert d’être documentée à travers des fonctionnalités et des scenarii : il en va de la sécurité des utilisateurs !

Pour une fonctionnalité donnée, chaque scenario s’exprime comme une phrase qui peut contenir :

• Une condition « Étant donné que... »
• Une action : « Quand … »
• Un traitement : « Alors …»
• Une navigation : « Alors … ».

Prenons un exemple :

Fonctionnalité : Afficher un programme d’exercices

Scenario 1 - Afficher un programme d’exercice pour un adhérent avec des contre-indications médicales

[Condition] Etant donné que l’utilisateur est connecté à son application

_[Condition] _Etant donné que l’utilisateur dispose d’au moins une contre-indication médicale

[Action] Quand l’utilisateur voit s’afficher un programme d’exercices

_[Traitement] _Alors on lui affiche les exercices du programme en lui indiquant ceux qui lui sont contre-indiqués (panneau d’alerte).

Détail d’implémentation : Dans le détail d’un exercice de l’appel GET /trainings/:id/exercices/:id vérifier si le tableau de contre-indications est non vide et s’il y a des contre-indications communes avec celles de l’utilisateur connecté.

Scenario 2 - Afficher un programme d’exercice pour un adhérent de sexe féminin

_[Condition] _Etant donné que l’utilisateur est connecté à son application

_[Condition] _Etant donné que l’utilisateur est de sexe féminin

_[Action] _Quand l’utilisateur voit s’afficher un programme d’exercices

_[Traitement] _Alors on lui affiche tous les exercices du programme propres à son genre

Détail d’implémentation : Dans le détail d’un exercice de l’appel GET /trainings/:id/exercices/:id récupérer le champs “gender” de type integer qui vaut 0 si c’est de genre féminin ou 1 si c’est de genre masculin.

L’ensemble des fonctionnalités et scenarii sont ainsi détaillés suivant ce modèle.

Ce format décliné en fonctionnalités puis en scenarii est inspiré d’un langage de tests appelé cucumber. Il permet notamment de décrire de manière méthodique et claire l’ensemble des cas d’usage.

Le document de spécifications se construit avec les designers et les développeurs et dispose de la granularité suffisante pour entamer les développements.

#4 - Spécifier la communication avec votre SI

Lors de l’écriture des spécifications fonctionnelles sous forme de fonctionnalités et de scenarii, l’équipe projet doit s’interroger sur la faisabilité technique de ce qui est souhaité. Ainsi, l’une des premières questions à se poser est la suivante : où et comment doit on récupérer les informations à afficher sur les interfaces ?

Il y a des informations écrites en dur dans le code de l’application : elles nécessitent une mise à jour de l’application pour être modifiées comme par exemple le titre des écrans ou le contenu des menus.

Certaines informations provenant d’une source extérieure : un serveur au sein d’un système d’information par exemple. Ces informations_ - les informations de compte ou le fil d’actualité d’un utilisateur par exemple -_ sont renvoyées par ce qu’on appelle des webservices.

La documentation des webservices est historiquement contenue dans des documents word ou swagger (dans le meilleur des cas). Mais ces éléments sont très rarement maintenus à jour et les informations divergent entre la théorie des documents et la réalité du webservice.

Aussi, lors des développements des fonctionnalités d’une application, nous avons généralement besoin de tester certains cas ce qui nous amène à écrire des bouchons : des données statiques d’exemple suivant le format décrit dans la documentation.

Et enfin, lorsque les webservices sont développés, il est important de tester ce qui est renvoyé.

Ainsi, notre spécification des webservices contient trois composantes :

• la documentation : la définition des ressources, les formats de requêtes et de réponses, les cas d’erreurs, etc. ;
• la génération de bouchons : les données statiques ;
• les tests.

Chez FABERNOVEL TECHNOLOGIES nous avons développé en interne notre propre outil de spécifications de webservices qui répond au standard de swagger OpenAPI Specification. Il sécurise et harmonise la spécification des webservices et garantit la bonne communication entre développeurs, designers, chef de projet et Product Owner.

Avec cet outil tout utilisateur peut rapidement :

• Décrire les ressources : un coach, un adhérent, un programme d'entraînement, des exercices, etc. ;
• Décrire les routes : créer un nouvel adhérent (_POST /members), _éditer les informations d’un adhérent (_PUT /members/:id), _créer un nouveau programme d'entraînement, (_POST /trainings), _etc. ;
• Générer des bouchons (ie. des données fictives) pour les développements ;
• Voir ce qui se passe dans la communication entre les serveurs et l’application (ie. tester les webservices).

Nous avons open sourcé le code de cet outil interne. N’hésitez pas à y jeter un oeil et à en déployer une instance chez vous. Nous serons ravis d’avoir vos retours !

Pour l’anecdote, c’était initialement un sujet de stage mais il est rapidement devenu un outil indispensable et un standard pour l’ensemble de nos projets.

[caption id="attachment_14789" align="aligncenter" width="1999"] Aperçu de notre outil de spécifications de webservices baptisé PERICLES en hommage au grand guerrier et stratège de l'âge d'or grec[/caption]

Pour plus d’informations sur la spécification de webservices, nous en parlions à Web2Day en juin 2018Web2Day en juin 2018.

#5 - Les spécifications, un indispensable de l’application mobile !

Les spécifications sont finalement les fondations de toute application. Elles permettent de développer un produit absolument conforme aux attentes du Product Owner et assurent un produit plus pérenne et maintenable sur le long terme.

Une fois votre produit spécifié : il ne vous reste plus qu’à le développer.

Vous découvrirez dans le prochain article comment bâtir une codebase SOLID suivant les principes du Clean Code.