Documentation utilisateur dans les interfaces
Il faudrait pouvoir avoir accès à une documentation directement depuis les interfaces.
Format de stockage de la documentation
Le format Markdown paraît tout à fait approprié. Il existe des bibliothèques javascript permettant le rendu des fichiers Markdown en HTML qui ne devraient pas être difficile à implémenter.
La difficulté résidera sur le lien à établir avec les images incluses dans la documentation et le lien entre les pages de la documentation.
La localisation des fichiers est à discuter. Il paraîtrait logique que les fichiers soient stockés dans src/calculators/nom_calculette. Avec comme nom de fichier nom_calculette.fr.md et nom_calculette.en.md. Les images référencées dans le fichier markdown se trouveront dans le même répertoire.
Ergonomie
A côté de l'icône permettant de fermer une calculette, on peut ajouter une icône d'aide permettant d'ouvrir la documentation de la calculette en cours. De la même manière, on peut ajouter cette icône à côté de chacun des boutons permettant d'ouvrir une nouvelle calculette sur l'écran de choix "Nouvelle calculette".
L'appui sur ce bouton d'aide permettra l'affichage à l'écran de la documentation correspondante avec en tête de la page un bouton de fermeture permettant de revenir à l'écran précédent.
Avec le router, on peut appeler un composant générique chargé d'effectuer le rendu HTML du fichier Markdown. Ce composant nécessitera qu'on lui passe deux paramètres : le type de calculette et l'identifiant de la page précédente pour pouvoir revenir en arrière à la fermeture de la documentation.
Des liens entre pages de la documentation seront nécessaires, un pré-traitement du fichier md sera peut-être nécessaire pour que les liens dont le format Markdown doit être décidé soient traduits en URL correspondant à ce qu'attendra le routeur pour afficher la doc.
Gestion des lacunes
Deux politiques sont possibles : la simple techniquement mais contraignante à l'usage, et l'automatique.
Soit le fichier de documentation est censé être présent dès le développement de la calculette avec éventuellement un fichier vide ou avec un message pénible du genre "Documentation non disponible".
Soit on gère la lacune du fichier de documentation (avec éventuellement un report vers la langue disponible si la documentation n'est pas traduite) à partir de la gestion de l'échec de lecture du fichier par le mécanisme promise qui permettrait de n'afficher le bouton d'aide que si le fichier de documentation est accessible.