Skip to content

Educational metric tooltips and English translation of the public showcase

Ticket #278: Educational metric tooltips and English translation of the public showcase
Type: Feature / User Experience / Decision Support
Affected Component: code_source_simule/tooltip_guidance.py, code_source_simule/flask_app.py, code_source_simule/portfolio_metrics.py, templates/_metric_tooltip.html, templates/dashboard.html, templates/demo_index.html, templates/titre_detail.html, docs/features/chapter4.md, docs/fr/features/chapter4.md, tests/, specs/019-add-metric-tooltips/

1. Context

This report continues my recent indicator deliveries with the same vision: turning the dashboard into a true decision-support tool while building a clear information foundation for the future advisory AI (see Project Vision).

Until now, indicator cards displayed reliable signals, but they assumed users already knew each metric's exact meaning and trigger threshold. For someone discovering the app, or for me after a pause, that required extra memory effort. At the same time, the public showcase and the demo holding-detail page still mixed French and English, which weakened the product's credibility for external audiences.

2. Objective

Make every indicator immediately understandable and actionable without leaving the page, and deliver a fully consistent English public showcase.

Concretely, the goals were to:

  • explain each metric directly on its card in plain language, with the related action to consider;
  • provide one-click access to the right detailed documentation section for deeper context;
  • keep the dashboard stable and readable even when some data points are missing;
  • standardize the public showcase and the demo holding-detail page in English, including date rendering.

3. What was delivered

  • Educational tooltips on all seven advanced metric cards: each card now includes a help point that explains metric meaning, trigger rule (explicit threshold), and suggested action. Opening behavior is hover on desktop and tap on mobile, with closing via outside click or Escape key.
  • Contextual documentation links: each tooltip points directly to its dedicated section in Chapter 4 (Investment Strategy). Labeling adapts to audience: "En savoir plus" on the secure dashboard and "Learn more" on the public demo.
  • Clear missing-data signaling: when a metric cannot be evaluated because required data is missing, the position is excluded and the tooltip explicitly shows "donnee insuffisante" instead of suggesting a misleading signal.
  • Documentation fallback state: if a reference link is absent or invalid, the tooltip displays an unavailable message and renders the link as non-clickable.
  • A more resilient dashboard: each indicator calculation is now isolated. One problematic input no longer blocks all cards; the dashboard remains stable and usable.
  • A fully English public showcase: the demo page and demo holding-detail page are now consistent in English, with English date formatting guaranteed regardless of server locale.
  • Stable documentation anchors: Chapter 4 (French and English versions) now includes dedicated anchors per concept to keep deep links reliable over time.

4. Business impact

  • Immediate understanding: each signal explains itself and its intended action, reducing interpretation effort and accelerating decisions.
  • User autonomy: direct links to the right documentation section make the dashboard pedagogical, without manual searching.
  • Stronger trust: explicit handling of missing data and unavailable links improves perceived reliability.
  • More credible showcase: a fully English demonstration presents a more professional and consistent product image.
  • Vision continuity: these structured explanations provide high-value context the future advisory AI can reuse to justify recommendations.

5. Validation and status

  • Full test suite green: 227 passed.
  • Key behaviors covered by dedicated tests: seven tooltip triggers on both views, accurate chapter-4 anchor links, split label between secure dashboard and demo, explicit missing-data signaling when required columns are absent, and uniform tooltip content contract (meaning, rule, action, link).
  • Non-regression confirmed: holding-detail tests aligned with the new English interface while preserving existing business cards.
  • Traceability: work delivered on branch ajout_indicateurs_demo, scoped by specs/019-add-metric-tooltips/.
  • Related tracking issue: #278.

6. Lessons learned

  1. A good indicator must be not only accurate but also effortless to understand. Explaining the metric exactly where it appears is more effective than relying on separate documentation that may never be opened.
  2. Isolating metric calculations makes the whole dashboard more robust: imperfect data degrades one card instead of compromising the entire page.
  3. Token usage summary: The gross consumption recorded for this implementation is $11.45 for 1142.32 Copilot AI credits. This cost increase compared to the trend observed in the most recent releases is justified by the scope of the changes involved in this release: a larger number of files to be read, analyzed and modified by the AI.