Comment rédiger une spécification destinée à un développeur ?

Nous voulions trouver un sujet qui ne soit pas trop technique et qui concerne un peu tout le monde. Quoi de mieux, donc, que le lien entre les techniques et les fonctionnels : la spécification technico-fonctionnelle ! En plus d’être contractuel avec le client, ce document permet de spécifier tout ce que le fonctionnel attend d’un développement et donc de satisfaire le client. Si la spécification n’est pas complète, le développement ne le sera pas et donnera au fonctionnel qui l’aura rédigé une mauvaise réputation aux yeux des développeurs. Chez nous c’est un document essentiel. En tant que développeur, il nous arrive souvent de recevoir une « spec », comme nous les appelons dans le langage familier, incomplète. Le manque de temps du rédacteur joue, mais il y a aussi le manque de connaissance de notre métier et ce dont nous avons besoin. Nous allons donc essayer de lister les points importants. Le schéma d’une bonne spécification commence par une explication large du besoin et va petit à petit entrer dans les détails. Il y aura tout d’abord la présentation client, la présentation du besoin fonctionnel, une partie technique, une partie test et pour finir une partie concernant la mise en production. La partie technique, une partie de la partie test et la partie concernant la mise en production sont renseignées par les développeurs. Hormis celles-ci, le fonctionnel devra rédiger le reste du document.

La définition des besoins du client

En général une spécification commence par la présentation client puis la présentation du besoin.

La première partie présente l’entreprise et son domaine, il est toujours intéressant de savoir pour qui l’on travaille.

La deuxième est une présentation globale du besoin. Cette dernière ne doit pas être négligée car elle nous permet d’avoir le contexte du développement. Il est important que nous comprenions dans quel cadre, quel module nous allons intervenir surtout si la demande s’inscrit dans un projet.

Si par exemple il s’agit d’une demande d’évolution réalisée par une autre entreprise, et que vous avez la chance d’avoir la spécification initiale, vous pourrez l’insérer à cet endroit, il y aura un suivi sur ce programme, flux, etc.

La description du besoin fonctionnel

Cette section commencera par une présentation générale de la demande. En général nous y mettons la situation actuelle et la situation attendue par le client. Exemple : Actuellement l’utilisateur saisit des données à la main dans SAP et l’entreprise souhaite automatiser ce traitement avec l’intégration de cette saisie via un fichier Excel afin de gagner du temps.

Pour les développements plus complexes, il est suivi d’un ou des schémas du flux dans lesquels s’inscrit le développement. Il m’est arrivé parfois de baser mon développement sur ces schémas lorsqu’il s’agissait de construire un flux complexe avec plusieurs entrées, traitements et sorties différents. Cela peut vraiment aider à comprendre le besoin.

Pour information, il existe par exemple en informatique les diagrammes d’UML (Unified Modeling Language). Certes, tous les diagrammes d’UML ne sont pas pertinents avec la majorité des développements sur SAP, mais certains diagrammes comme celui de séquence et/ou le diagramme global d’interaction sont particulièrement pertinents lors de la création de cette visualisation.

Ces deux premières parties sont en général rédigées, ce sont parfois même les seules. Nous entrons donc dans le vif du sujet : quels sont les besoins des développeurs pour livrer le développement attendu ?

En gardant en tête que l’on part du plus abstrait au plus détaillé. Après avoir spécifié le besoin dans sa globalité il faut donc spécifier les « détails ». Le plus simple est de décrire ces détails en déroulant le flux à développer.

Quel est le point de départ ?

Un écran de sélection :

Nous listons donc les paramètres, select option et leurs textes spécifiques si ceux du standard ne conviennent pas
Nous pensons à leurs traductions si nécessaires
Les types des champs
Les champs obligatoires
Le fonctionnement de l’écran si celui-ci a des radio boutons, y a-t-il des sections visibles/invisibles ?
Le programme doit-il être utilisé en avant plan, arrière-plan ou les deux ? Cela est important s’il y a un fichier à intégrer par exemple
Si un fichier doit être intégré, quel est son type (Pour info un CSV ≠ XLS) ? Est-ce un fichier sur le PC de l’utilisateur ou sur le serveur SAP ?
Dans le cas d’un fichier à récupérer sur le serveur SAP, quel est le fichier ? Existe-t-il un chemin logique ?
Nom de la transaction à créer si nécessaire

Un exit :

Quelle transaction est concernée ?
Quelles actions le déclenchent ?
Quelles sont les données qui encadrent cet exit ?

Une interface sortante ou entrante :

Paramètres d’entrées et sorties ainsi que leur type
Paramétrage de la communication lorsqu’il s’agit d’Idoc
La volumétrie
Si l’interface communique en dehors de SAP, avec qui communique-t-elle et comment ?

Table de paramétrage :

Les types des champs
Spécifier les champs clefs
Ne pas oublier de faire une SCC1 lorsque l’environnement de dev est multi mandant

Formulaire :

Si création de formulaire, le paramétrage de l’output doit être fait sinon nous ne pouvons pas tester
Ne pas oublier de renseigner l’output
Les langues dans lesquelles le formulaire sera utilisé

Autorisations :

Quels sont les objets concernés ?
Si le développeur est chargé de la matrice des rôles, quels sont les rôles à modifier ? Cette modification doit-elle être validée par quelqu’un d’autre ?

Quel est le traitement ?

Règles de gestion :

S’il y a de multiples sélections à faire en table, spécifier le lien entre ces tables. Dans l’idéal tous les champs en clef doivent être utilisés !
Quand il y a beaucoup de règles de gestion, il vaut mieux nous les mettre dans un fichier Excel plutôt que par écrit un peu partout, c’est plus lisible et il y aura moins d’oublis
Soyez le plus précis possible dans l’explication du flux en décrivant les étapes souhaitées. Prenez les choses dans l’ordre, par exemple, « A la sauvegarde de la transaction X, un job sera déclenché et celui-ci exécutera le programme Y, qui devra lister les erreurs avec le message e1, e2, etc. et succès s1, s2, etc. en SLG1 ».
Lorsqu’une valeur doit être récupérée mais que celle-ci est calculée à l’écran et n’est pas stockée en table, ce qui est souvent le cas des conditions de prix par exemple, le calcul doit être impérativement spécifié ! Pas de formule = pas de calcul.
Le traitement a-t-il des points de blocage ? Si oui, doit-on afficher un message ? Si oui lequel ? Doit-il s’afficher à l’écran ? Un log ? Un pop-up ?

Report ALV :

Est-il modifiable ? Si oui, y a-t-il des contrôles à effectuer sur les zones saisissables ?
La structure doit être spécifiée
Un mapping est le bienvenu
Y a-t-il un tri sur les données à afficher ?

Formulaire :

Lors d’une création, une maquette est absolument nécessaire ainsi que le type et la taille des polices
Le logo si nécessaire
Les noms des libellés et leur traduction
Où se situe les données à récupérer ? Nom de table, Screenshot de la donnée à récupérer en transactionnel, règle de calcul, condition d’affichage

Petite remarque sur la récupération des zones depuis une transaction. Il vaut mieux nous indiquer les champs dans un Screenshot plutôt que de nous donner le nom technique de la zone de travail. Le plus souvent, lorsque l’aide à la recherche est utilisée (F1) sur un champ, celui-ci n’est pas lié à une table mais à une structure, la donnée n’est donc pas stockée à l’endroit indiqué.

Exemple : En ME23N, si vous faites F1 sur la sales org le « nom de table » est MEPO1222 alors que la donnée est stockée dans la table EKKO.

Pourquoi préférons-nous partir depuis le champ de la transaction ?
Il existe plusieurs raisons :

1
Pour tester il faut que l’on sache où se trouve les données à l’écran
2
Le nom technique ne nous dit pas où il se trouve dans l’écran et l’on va devoir faire F1 sur tous les champs
3
Et si nous ne connaissons pas la table où est stockée la donnée, nous allons devoir débugger le standard et il est plus simple de savoir où nous nous situons dans l’écran plutôt que d’avoir uniquement un champ technique

Quelle est la restitution ?

Intégration de données :

Faut-il un ALV ? Si oui quelle est sa structure ?
Faut-il un log ? Si oui, les noms des objets et sous objets pour la consulter en SLG1
Le fichier doit-il être rejoué ?
Dans le cas d’un fichier à déposer sur le serveur SAP, quel est le fichier ? Passe-t-on par un chemin logique ?

ALV :

Est-il éditable ? Si oui, y a-t-il un retraitement des données ?
Les lignes sont-elles sélectionnables ?
Doit-on ajouter des boutons spécifiques ?

Mail :

Contrôler que l’environnement (SOST, SCOT) fonctionne correctement

Test

La partie consacrée aux tests est la plus négligée des spécifications. Elle est pourtant essentielle, sans données de test nous ne pouvons pas commencer le développement !

Dans le premier retour que l’on fait au fonctionnel lorsque l’on reçoit une spécification, il y a quasiment toujours « Il me faut un jeu de test » … Ce n’est pas de la mauvaise volonté de notre part, mais le problème est tout simplement : comment tester l’avancée de notre travail si nous n’avons aucune matière ? C’est comme demander à un garagiste de réparer une voiture qui ne démarre pas et dans laquelle il n’y aurait pas de carburant. Le garagiste peut effectuer une réparation mais n’aura aucun moyen de savoir si la réparation a fonctionné puisqu’il ne peut pas la démarrer. C’est exactement pareil en développement informatique, comment tester un développement si l’on n’a pas les données qui le font fonctionner ?

Il nous faut donc impérativement :

Un mode opératoire expliquant comment tester
Dans le cas d’une correction d’anomalie, reproduction du problème au minimum en qualité, et pour la résolution un cas de test en dev est également nécessaire !
Des cas de test de non-régression s’il s’agit d’une évolution
Vérification que les N° des documents donnés ne soient pas obsolètes ou inutilisables

En résumé

Un point sera nécessaire entre le développeur et le fonctionnel, mais il sera nettement plus court si la spécification est exhaustive. Le temps de développement sera également raccourci si le document est clair et précis.

Finalement, nous pouvons nous dire que les besoins des développeurs sont quasiment les mêmes que ceux des fonctionnels. Si un fonctionnel reprend le sujet sans le connaitre et que la partie qui lui est destinée est correctement rédigée, il pourra s’y retrouver seul.

Si après cette lecture vous vous dites « Quel est l’intérêt de cet article ??? » Bravo !
Vous êtes déjà l’ami des développeurs !
Sinon nous espérons que cela vous aidera à mieux comprendre nos besoins.