Créer une application web sur Bubble est une étape passionnante, mais une fois que votre projet est lancé, il est essentiel de rédiger une documentation claire et complète. Que vous développiez une application pour vous, une équipe interne, un client ou un large public, la documentation est cruciale pour assurer une bonne maintenance, faciliter l'adoption par les utilisateurs, et garantir la pérennité de votre projet. Elle sert également de référence pour les futurs développeurs qui pourraient intervenir sur l’application.

Dans cet article, je vais vous présenter une méthodologie claire pour rédiger la documentation de votre application Bubble. Nous aborderons les différentes sections que votre documentation devrait contenir, les outils à utiliser et des bonnes pratiques pour rendre vos explications accessibles à tous.

Pourquoi rédiger une documentation ?

Avant de plonger dans la méthodologie, il est important de comprendre pourquoi une documentation bien structurée est cruciale pour votre app.

Faciliter la prise en main de l’application

Une bonne documentation permet aux utilisateurs, qu’ils soient clients ou membres de votre équipe, de comprendre comment utiliser l’application. Elle offre des instructions claires et précises sur les fonctionnalités et les processus intégrés.

Garantir la maintenance et les mises à jour

Si vous ou d’autres développeurs devez effectuer des modifications ou des mises à jour sur l’application à l’avenir, une documentation bien rédigée sert de feuille de route. Elle détaille la structure, les workflows et les fonctionnalités, ce qui permet de comprendre rapidement comment l’application fonctionne.

Aider à l'intégration de nouveaux utilisateurs

Lorsque de nouveaux utilisateurs rejoignent votre équipe ou que des développeurs externes prennent en charge le projet, la documentation facilite leur intégration. Elle leur permet de comprendre rapidement l'architecture de l'application et les fonctionnalités clés sans avoir à parcourir chaque détail dans l'éditeur de Bubble.

Les sections essentielles d'une documentation d’application

Pour être efficace, la documentation doit être organisée et structurée de manière logique. Voici les sections principales que vous devriez inclure :

Introduction et aperçu du projet

La première section de votre documentation devrait offrir une vue d'ensemble du projet. Elle doit répondre aux questions suivantes :

• Quel est l'objectif de l’application ?

• À qui s'adresse-t-elle ?

• Quelles sont les principales fonctionnalités ?

Cette partie doit rester concise et donner une vision globale de l’application.

• Exemple : "Cette application permet aux utilisateurs de gérer leurs projets en créant des tâches, en définissant des priorités et en suivant leur avancement via un tableau de bord intuitif. Elle est destinée aux freelances et petites équipes de projet."

Architecture de l'application

L’architecture de l’application est l'une des parties les plus importantes de la documentation, car elle décrit comment l'application est structurée dans Bubble. Il est crucial d'expliquer la logique des pages, les types de données et les workflows.

1. Structure des pages

Détaillez la structure des pages de votre application et leur rôle respectif. Cela aide à comprendre comment les différentes pages interagissent entre elles.

• Exemple : La page d’accueil, la page de gestion de projets, la page des paramètres, etc.

2. Types de données

Décrivez les data types que vous avez configurés dans l'application. Pour chaque data type, précisez les fields associés et leur rôle dans l'application.

• Exemple : Data type "Projet" avec des fields tels que "Nom du projet", "Date de début", "Date de fin", "Responsable", "Priorité".

3. Workflows principaux

Les workflows sont les processus automatisés qui se déclenchent lors d’actions utilisateur ou d'événements spécifiques. Cette section devrait décrire les workflows clés de l’application, par exemple : inscription d'un utilisateur, soumission d’un formulaire, envoi d’une notification.

Documenter les fonctionnalités utilisateur

Les développeurs qui liront la documentation doivent être en mesure de comprendre comment utiliser les fonctionnalités de l’application. La documentation doit décrire de manière détaillée chaque fonctionnalité, son objectif et comment elle fonctionne.

Explication des actions principales

Pour chaque action que l’utilisateur peut accomplir, fournissez des instructions pas à pas sur son fonctionnement. Les explications doivent être claires et, idéalement, accompagnées de captures d'écran ou de vidéos pour illustrer le processus.

• Exemple :

  • Créer un nouveau projet : L'utilisateur doit cliquer sur "Nouveau projet", entrer un nom et une description, puis appuyer sur "Enregistrer".

  • Modifier un projet existant : L'utilisateur clique sur l'icône de modification, change les informations du projet et enregistre les modifications.

Gestion des erreurs et messages d’alerte

Précisez comment l’application gère les erreurs et quelles sont les notifications ou messages d’alerte qui apparaissent pour guider l'utilisateur. Documentez les cas dans lesquels l'utilisateur peut rencontrer des erreurs (comme des champs obligatoires non remplis) et les solutions proposées par l'application.

Décrire les workflows avancés et intégrations

Si votre application Bubble comporte des workflows complexes ou des intégrations tierces (par exemple, avec des API ou des services externes comme Stripe ou Google Maps), cette section doit les détailler de manière exhaustive.

Workflows conditionnels et dynamiques

Si votre application contient des workflows conditionnels, expliquez les conditions spécifiques qui déclenchent certaines actions. Détaillez aussi comment les workflows dynamiques fonctionnent, en fonction des données saisies par l’utilisateur.

• Exemple : Si un utilisateur est administrateur, il aura accès à certaines fonctionnalités supplémentaires dans l’interface. Le workflow doit être détaillé pour expliquer comment cette différenciation est gérée.

Intégrations API

Si votre application se connecte à des services externes via des API, vous devez inclure une section qui explique comment l’intégration a été configurée. Cela inclut les clés API, les endpoints utilisés, et les données échangées.

• Exemple : Si vous avez intégré Stripe pour les paiements, expliquez comment le paiement est géré, depuis la soumission de la carte de crédit jusqu’à la confirmation de la transaction.

Automatisation et workflows API

Documentez également les workflows API que vous avez mis en place pour automatiser certaines actions dans l'application. Cela peut inclure des tâches répétitives automatisées, des envois d’emails, ou la création automatique de rapports.

Documentation technique pour les développeurs

Cette section est dédiée à des informations techniques que vous souhaitez partager avec les développeurs. Elle peut inclure :

Structure de la base de données

Fournissez une documentation détaillée de la structure de votre base de données. Décrivez les types de données, les relations entre ces données, ainsi que les requêtes complexes utilisées.

Pour en savoir plus sur la base de données, lisez l'article dédié.

Liste des custom states

Si vous utilisez des custom states pour gérer des informations temporaires, documentez-les également. Cela permet à un futur développeur de comprendre comment ces états sont utilisés et comment ils influencent le comportement de l’application.

• Exemple : Un custom state "onglet actif" qui détermine quel onglet du tableau de bord est actuellement sélectionné.

Pour en savoir plus sur les custom states, lisez l'article dédié.

Plugins et dépendances externes

Si vous utilisez des plugins spécifiques dans votre application, listez-les avec une brève explication de leur rôle et comment ils sont configurés.

• Exemple : Le plugin Stripe utilisé pour gérer les paiements récurrents des abonnements des utilisateurs.

Utiliser des outils pour rédiger la documentation

Rédiger la documentation de votre application peut sembler fastidieux, mais plusieurs outils peuvent faciliter le processus :

Notion ou Google Docs

Utilisez des outils comme Notion ou Google Docs pour organiser votre documentation de manière claire et collaborative. Vous pouvez structurer les sections, ajouter des commentaires, et collaborer avec d'autres membres de l'équipe.

Outils de documentation intégrée

Certains outils comme ReadMe ou GitBook permettent de créer des documentations interactives avec des sections dynamiques, des recherches intégrées et des hyperliens entre les différentes sections.

Intégration de vidéos et captures d’écran

Pensez à intégrer des vidéos explicatives et des captures d'écran pour rendre la documentation plus visuelle. Utilisez des outils comme Loom pour enregistrer des tutoriels vidéo et les intégrer directement dans la documentation.

Personnellement j'utilise Loom pour gérer toutes les questions que me posent mes élèves en coaching Bubble, je peux vous dire que cela fonctionne très bien !

Bonnes pratiques pour rédiger une documentation efficace

Restez simple et clair

La clarté est essentielle. Rédigez vos explications de manière simple et directe, en évitant le jargon technique si ce n'est pas nécessaire. Pensez toujours à vos utilisateurs finaux.

Soyez exhaustif mais concis

Il est important que la documentation soit complète, mais essayez de ne pas surcharger les utilisateurs avec des informations superflues. Allez à l’essentiel pour que les utilisateurs puissent trouver rapidement ce qu’ils cherchent.

Mettez à jour régulièrement

Les applications évoluent, et votre documentation doit suivre. Assurez-vous de mettre à jour régulièrement la documentation pour refléter les nouvelles fonctionnalités ou les modifications apportées à l’application.

Conclusion

Rédiger la documentation de votre application Bubble est une étape essentielle pour assurer la pérennité de votre projet. Que ce soit pour les utilisateurs finaux ou pour les développeurs qui pourraient intervenir sur l’application à l’avenir, une documentation claire et bien structurée facilite la maintenance, l’adoption, et l’évolution de votre application.

En suivant la méthodologie présentée dans cet article, vous serez en mesure de rédiger une documentation complète, couvrant toutes les facettes de votre application : des pages aux workflows, en passant par les intégrations API et les données. N'oubliez pas d’utiliser des outils collaboratifs pour structurer efficacement vos informations et de mettre à jour votre documentation au fur et à mesure des changements dans votre application.

Bonne rédaction ! ;)