Notes templates
Explication
Les notes viennent compléter une explication plus complète et précise sur les besoin du module, la configuration et surtout expliquer la raison d’être de ce module à cet instant précis du scénario.
Les notes sont indispensables afin de pouvoir maintenir sur le long terme le scénario à la fois en développement et en production.
Convention de nommage
Pour gagner en productivité, nous avons choisi de créer un template structuré de Notes permettant de rédiger les fonctionnalités sur chaque module.
Le template utilise le markdown pour la rédaction.
Quel est l’intérêt ? Le markdown est un format compréhensible sur le web et très largement répandu. Il est donc compatible en règle générale avec beaucoup d’outils lorsque vous allez faire des copier-coller (Notion, Monday, Github, n8n…). Même si certains outils ne le supportent pas encore, nous conseillons vivement de choisir cette méthode d’écriture qui apporte le plus de flexibilité.
TEMPLATE
## [MODULE NAME][IDENTIFIANT]## [GOAL]### [DETAILS]
Détails
Voici une explication détaillé du template
| NAMING | DESCRIPTION | PRÉSENCE |
|---|---|---|
| MODULE NAME | Le nom que vous avez donné au module | Obligatoire |
| IDENTIFIANT | L’identifiant du module si l’outil d’automatisation vous le donne. L’identifiant vous donne en règle générale l’ordre dans lequel le module a été créé, mais pas forcément sa place dans le scénario. L’idée de l’identifiant est surtout qu’il puisse être facilement retrouvé. | Optionnelle |
| GOAL | Vous devez définir avec précision la raison d’être précise du module et son rôle dans le scénario. | Obligatoire |
| DETAILS | Si vous avez des détails à apporter pour mieux comprendre un ou plusieurs points techniques liés au module, il faut le faire ici. | Optionnelle |
Considérations générales :
- Les titres doivent être présents
- Les titres peuvent être en dans votre langue natale
- Les crochets sont optionnels, mais permettent de séparer pour la lecture.
- Attention, pour que le copier-coller fonctionne, il faut un espace entre les ## et le titre.
- Pensez à sauter des lignes. Encore une fois, l’idée est surtout d’améliorer la lisibilité. Meilleure lisibilité = meilleure productivité.
- Ne vous restreignez pas sur la quantité. L’objectif n’est pas de documenter pour documenter, mais de “documenter utile”. Par conséquent si vous devez écrire beaucoup et que votre note est longue, dites-vous que c’est pour le bien de la maintenabilité.
Exemples
Voici un exemple dans la manière de rédiger ses notes avec Predict_Flow :
Le module pris en exemple est un module Brevo (envoi de mail).
## NOM DU MODULE [1]## GOAL
Le module sert à envoyer un email à toutes les personnes présentes dont le statut a changé de “en cours” à “intéressé”. Cet email contient également un formulaire Tally dont les informations seront récupérées dans le scénario nommé : [PROD][Gestion des données du formulaire Tally][john@crew.co][2024-06-02]_V1## DETAILS
- Les paramètres passés dans l’envoi correspondent aux variables dynamiques définies dans le template sur Brevo.
- Le formulaire tally est envoyé avec un lien possédant une URL avec des query parameters spécifiques. Ces dernières sont définies en hidden fields directement dans le formulaire Tally.