Docs fonctionnelles publiques — Documentation Fonctionnelle

Exposition publique (sans connexion) des documentations fonctionnelles du projet, sous forme de markdown brut, afin qu'un LLM puisse les récupérer directement (rédaction de cahier des charges, notes de cadrage, etc.).

À quoi ça sert

Lorsqu'on prépare un cahier des charges ou une note de cadrage avec l'aide d'un LLM (ChatGPT, Claude…), il est utile de lui fournir la documentation fonctionnelle existante d'ISI-APP comme contexte. Copier-coller les fichiers un par un est fastidieux.

Cette fonctionnalité publie le contenu du dossier docs/ (documentation fonctionnelle) sur des URL publiques accessibles sans authentification. On peut ainsi donner directement une URL au LLM : il récupère le markdown brut et dispose du « quoi » et du « pourquoi » de la fonctionnalité concernée.

Comment ça marche (côté utilisateur)

Page d'index

• URL de l'index : /public-docs
• Il s'agit d'une page card autonome et navigable, qui liste toutes les documentations fonctionnelles disponibles, regroupées par module (crm, tickets, platform, gmao…).
• Chaque entrée affiche son titre, son statut (active, draft, deprecated…) et sa date de dernière revue.
• Les documents sont triés par titre à l'intérieur de chaque module.

Récupérer une doc

Chaque card propose deux actions :

• « Copier l'URL » : copie l'URL publique dédiée de la doc (ex. /public-docs/platform/public-functional-docs.md). Cette URL renvoie le markdown brut (type text/markdown), sans mise en forme : exactement ce dont un LLM a besoin en contexte. C'est ce lien qu'on transmet à l'assistant IA.
• « Ouvrir » : ouvre une version HTML mise en forme et lisible de la doc (même URL suffixée de ?format=html), pour qu'un humain puisse la parcourir confortablement (titres, tableaux, blocs de code stylés). Depuis cette page, on peut revenir à l'index ou récupérer à nouveau le lien markdown.

En résumé : markdown brut pour l'IA, HTML mis en forme pour l'humain, à partir du même document.

Périmètre

• Seule la documentation fonctionnelle du dossier docs/ est exposée (le « quoi » / « pourquoi », destiné à l'utilisateur et au chef de projet).
• La documentation technique (.claude/technical-docs/, archi, code, patterns) et les records internes (ADR, audits) ne sont jamais exposés.
• Les gabarits (_templates) sont exclus de la liste et inaccessibles.
• Seuls les fichiers .md sont servis.

Règles d'accès

• Accès public : aucune connexion ni droit particulier n'est requis. Toute personne disposant de l'URL peut lire ces documents.
• N'exposer via docs/ que du contenu fonctionnel destiné à être partageable — c'est la contrepartie de l'accès public.

Référencement (SEO & GEO)

La page étant destinée à être liée depuis le site vitrine WordPress isi-app, elle est optimisée pour les moteurs de recherche (SEO) et les moteurs génératifs / IA (GEO) :

• Les pages HTML (index et vue doc mise en forme) sont indexables (index, follow) et portent : balise title, meta description (extraite du contenu), URL canonical, balises Open Graph + Twitter Card (bel aperçu au partage Slack/Teams/WordPress), et des données structurées JSON-LD (CollectionPage pour l'index, TechArticle pour chaque doc).
• Un sommaire (TOC) cliquable et la coloration syntaxique des blocs de code améliorent la lecture.
• Un sitemap est exposé sur /public-docs/sitemap.xml (à soumettre dans la Search Console).
• GEO : chaque page doc annonce sa version Markdown propre via <link rel="alternate" type="text/markdown">, et le markdown brut reste servi tel quel — format idéal pour l'ingestion par un LLM.
• Le markdown brut (.md) reste en X-Robots-Tag: noindex pour éviter le contenu dupliqué : c'est la page HTML qui est référencée.

Points d'attention

• Confidentialité : le contenu étant public et désormais indexable, ne jamais placer d'information sensible ou confidentielle dans docs/.
• Limitation de débit : les URL publiques sont protégées par un throttle (60 requêtes/minute) pour éviter les abus.
• Sécurité des chemins : les tentatives d'accès en dehors de docs/ (path-traversal, fichiers non .md, gabarits) sont bloquées et renvoient une erreur 404.

Voir aussi

• Documentation technique : .claude/technical-docs/platform/public-functional-docs.md