Skip to content

README.md

Latest commit

 

History

History
298 lines (230 loc) · 15 KB

README.md

File metadata and controls

298 lines (230 loc) · 15 KB
Raw

BP-AIR — Fiches de bonnes pratiques · Architecture Informatique Responsable

Espace de travail collaboratif du Groupe de Travail AIR (Institut du Numérique Responsable — INR / ISIT) pour co-écrire les fiches de bonnes pratiques et les publier automatiquement sous forme de site web.

🌐 Site en ligne : https://institut-du-numerique-responsable.github.io/BP-AIR/

1. Le principe en une phrase

Vous écrivez du Markdown (texte simple) dans ce dépôt → un robot le transforme en site web et le publie tout seul. Aucune mise en forme manuelle, aucun outil à installer pour contribuer.

2. Comment ça marche (architecture)

                 ┌─────────────────────────────────────────--─┐
   Vous éditez   │  Dépôt GitHub (les fichiers .md)           │
   une fiche  ──►│  docs/fiches/*.md  +  docs/guide-unifie.md │
                 └───────────────────┬─────────────────────--─┘
                                     │  push / merge sur "main"
                                     ▼
                 ┌──────────────────────────────--────────────┐
   Automatique   │  GitHub Actions (.github/workflows)        │
   (~30 s)       │  1. installe MkDocs Material               │
                 │  2. construit le site (HTML)               │
                 │  3. le déploie sur GitHub Pages            │
                 └───────────────────┬─────────────────--─────┘
                                     ▼
                 ┌───────────────────────────────────────-───┐
   Résultat      │  Site public, à jour                      │
                 │  institut-du-numerique-responsable        │
                 │       .github.io/BP-AIR/                  │
                 └────────────────────────────────────────-──┘

Briques techniques :

Élément Rôle
Markdown (.md) Le contenu, écrit par le GT. Source unique de vérité.
MkDocs + thème Material Moteur qui transforme le Markdown en site (menu, recherche, thème clair/sombre).
mkdocs.yml Configuration : titre, navigation par thème, options.
GitHub Actions (.github/workflows/deploy.yml) Construit et déploie le site à chaque modification de main.
GitHub Pages Héberge le site public gratuitement.

Personne n'a besoin de comprendre cette mécanique pour contribuer. Elle tourne seule.

3. Structure du dépôt

BP-AIR/
├── docs/                       # tout le contenu du site
│   ├── index.md                # page d'accueil
│   ├── guide-unifie.md         # fondations théoriques (6 piliers, matrice, outils, glossaire)
│   ├── contributeurs.md        # autrices, auteurs et intervenants du GT
│   ├── robots.txt              # indexation, moteurs et robots IA
│   ├── assets/
│   │   ├── img/                # illustrations et schémas (WebP + SVG)
│   │   └── extra.css           # styles (figures, zoom, bandeaux de statut)
│   └── fiches/                 # une fiche = un fichier .md
│       ├── G1-mandat.md
│       ├── ...
│       └── D2-communiquer-valoriser.md
├── overrides/                  # surcharges du thème
│   ├── main.html               # bandeau de statut + balises SEO / JSON-LD
│   └── partials/copyright.html # pied de page et logos
├── hooks/llms.py               # génère llms.txt et llms-full.txt au build
├── TEMPLATE-fiche.md           # modèle à copier pour créer une fiche
├── mkdocs.yml                  # configuration + navigation
├── requirements.txt            # dépendances épinglées
├── CONTRIBUTING.md             # guide détaillé de contribution
├── SECURITY.md                 # signalement de vulnérabilité
├── CITATION.cff                # métadonnées de citation
├── LICENSE                     # CC BY-SA 4.0
├── README.md                   # ce fichier
└── .github/
    ├── workflows/deploy.yml    # build + déploiement automatiques
    ├── workflows/liens.yml     # vérification mensuelle des liens externes
    ├── CODEOWNERS              # relecteurs par défaut
    ├── PULL_REQUEST_TEMPLATE.md
    └── ISSUE_TEMPLATE/fiche.md

Les 18 fiches, par thème

Code Thème Fiches
G1–G4 Gouvernance et stratégie Mandat · Parties prenantes · Objectifs et ODD · Feuille de route
M1–M2 Mesure et diagnostic Diagnostic · Pilotage et KPI
C1–C5 Conception sobre Éco-conception des services · Cycle de vie des données · IA sobre · Dette d'intégration · Accessibilité
I1–I3 Infrastructure et matériel Infrastructures et environnements · Achats responsables · Résilience et sobriété
V1–V2 Chaîne de valeur Maturité des parties prenantes · Souveraineté et réversibilité
D1–D2 Déploiement et valorisation Conformité · Communiquer et valoriser

4. Utiliser le site (lecture)

Rien à installer. Ouvrez https://institut-du-numerique-responsable.github.io/BP-AIR/ :

  • Menu de gauche : les fiches rangées par thème.
  • Barre de recherche (en haut) : recherche plein texte dans tout le contenu.
  • Bouton clair/sombre (en haut).
  • Le site est responsive (lisible sur mobile).

5. Éditer une fiche (le plus simple — dans le navigateur)

Pas besoin de Git en ligne de commande.

  1. Sur le site ou GitHub, ouvrez le fichier de la fiche dans docs/fiches/.
  2. Cliquez sur l'icône crayon ✏️ (« Edit this file »). (Astuce : depuis la page d'accueil du dépôt, la touche . ouvre un éditeur web complet, github.dev.)
  3. Modifiez le texte en respectant les sections du modèle (Objectif, Contexte, Étapes, KPIs, Pièges…).
  4. En bas : Commit changes → choisissez « Create a new branch and start a pull request ».
  5. Un autre membre relit et approuve la Pull Request, puis la merge.
  6. ~30 s plus tard, le site est à jour automatiquement.

Créer une nouvelle fiche

  1. Copiez TEMPLATE-fiche.md dans docs/fiches/ en la nommant CODE-titre-court.md (ex. G5-formation.md).
  2. Remplissez l'entête --- (frontmatter) : id, titre, theme, proprietaire, contributeurs…
  3. Ajoutez-la dans mkdocs.yml (sous le bon thème) et dans le tableau de docs/index.md.
  4. Ouvrez une Pull Request.

L'entête de chaque fiche (frontmatter)

---
id: C1
titre: Éco-concevoir les services numériques
theme: Conception sobre
statut: brouillon        # brouillon → en-revue → validé
proprietaire: INR/ISIT   # entité détentrice de la fiche
contributeurs: [Prénom Nom]   # rédacteurs ; ajoutez-vous quand vous contribuez
reviewers: []
version: 0.1
maj: 2026-06-04
---
  • Ajoutez votre nom dans contributeurs quand vous travaillez sur une fiche (évite les éditions concurrentes : voyez qui est déjà dessus).
  • Passez statut à en-revue quand la fiche est prête, validé quand le GT l'a actée.
  • Avant validé, supprimez la section « Notes de coédition » en bas de fiche.

Ajouter une image / un schéma

  1. Déposez le fichier dans docs/assets/img/ (nom explicite, ex. cartographie-urbanisation.webp). Format WebP pour les images matricielles, SVG pour les schémas vectoriels : cwebp -q 82 schema.png -o schema.webp.

  2. Insérez-le dans une fiche/section avec une légende — le zoom plein écran au clic est automatique :

    <figure markdown>
  ![Texte alternatif décrivant l'image](../assets/img/mon-schema.webp)
  <figcaption>Légende affichée sous l'image.</figcaption>
</figure>

    Chemin : assets/img/... depuis index.md / guide-unifie.md, ../assets/img/... depuis une fiche dans docs/fiches/.

  3. Renseignez toujours le texte alternatif (accessibilité) et créditez la source si l'image n'est pas la vôtre.

⚖️ Les schémas issus des publications INR/ISIT sont sous licence CC BY-SA 4.0, comme l'ensemble de ce dépôt (voir §10) : attribution + même licence obligatoires.

Détail complet du workflow et des règles d'écriture : CONTRIBUTING.md.

6. Travailler à plusieurs (branche protégée + Pull Requests)

La branche main est protégée : personne ne pousse directement dessus. Toute évolution passe par une Pull Request (PR) relue. C'est ce qui rend la coédition sûre — rien n'arrive en ligne sans relecture, et l'historique reste propre.

Règles en vigueur sur main

  • ❌ Pas de push direct sur main.
  • ✅ Toute modification via une branche + une Pull Request.
  • 👁️ 1 approbation d'un autre membre minimum avant de pouvoir fusionner.
  • 🤖 La construction du site doit réussir (vérification automatique build, qui lance mkdocs build --strict : liens cassés, navigation invalide = PR bloquée).
  • 🔄 La PR doit être à jour avec main avant fusion.

Le parcours d'une évolution ou d'une correction

1. Créer une branche       (depuis main)
        │
2. Modifier la / les fiche(s) en Markdown
        │
3. Ouvrir une Pull Request  → décrire le changement
        │
4. Vérification auto "build" (mkdocs --strict)   ──┐
        │                                          │ doivent être OK
5. Relecture + approbation d'un membre  ───────────┘
        │
6. Fusion (Merge) dans main
        │
7. Déploiement automatique → site à jour (~30 s)

A. Tout dans le navigateur (recommandé pour la plupart)

  1. Ouvrez la fiche dans docs/fiches/, cliquez ✏️ Edit.
  2. Faites vos modifications.
  3. Commit changes → cochez « Create a new branch and start a pull request » → nommez la branche (ex. correction-C1-typo) → Propose changes.
  4. Renseignez le titre/description, Create pull request.
  5. Attendez le ✅ de la vérification build, demandez la relecture (Reviewers).
  6. Après approbation, cliquez Merge pull request. Le site se met à jour seul.

B. En local avec Git (pour les contributions plus larges)

git clone https://github.com/Institut-du-Numerique-Responsable/BP-AIR.git
cd BP-AIR
git switch -c ma-contribution          # nouvelle branche
# … éditer les fichiers, prévisualiser avec « mkdocs serve » (voir §7) …
git add -A && git commit -m "Décrit le changement"
git push -u origin ma-contribution
gh pr create --fill                    # ou ouvrir la PR depuis l'interface GitHub

Bonnes pratiques

  • Une PR = un sujet (une fiche ou une correction ciblée) → relecture plus simple, fusion plus rapide.
  • Ajoutez-vous dans contributeurs (frontmatter) de la fiche travaillée.
  • Nom de branche parlant : ajout-G5-formation, maj-outils-I1, correction-liens-C2.
  • Répondez aux commentaires de relecture en poussant de nouveaux commits sur la même branche (la PR se met à jour automatiquement).

7. Prévisualiser en local (optionnel, pour les plus à l'aise)

Pour voir le rendu avant de pousser :

git clone https://github.com/Institut-du-Numerique-Responsable/BP-AIR.git
cd BP-AIR
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
mkdocs serve            # ouvre http://127.0.0.1:8000 (recharge auto)

8. Contribuer sans Git (alternative)

Pour les membres bloqués par Git ou par les règles de sécurité de leur entreprise : rédigez le brouillon dans HackMD (https://hackmd.io, Markdown en temps réel, commentaires), puis un membre à l'aise avec Git reporte le contenu validé dans le dépôt via une Pull Request.

9. Publication — résumé

Question Réponse
Qui publie ? Personne manuellement — GitHub Actions le fait à chaque merge sur main.
Combien de temps ? ~30 secondes après le merge.
Où voir l'état ? Onglet Actions du dépôt.
Coût ? Gratuit (dépôt public + GitHub Pages).

10. Référencement (moteurs et assistants IA)

Le site est outillé pour être trouvé et correctement cité, y compris par les assistants IA, un enjeu direct pour un travail sous CC BY-SA, dont l'attribution est une obligation de licence.

Dispositif Où Rôle
Description propre à chaque page description: dans le frontmatter Évite la description générique dupliquée sur les 16 pages, principal frein au classement.
Open Graph + Twitter Card overrides/main.html Aperçu correct au partage (LinkedIn, Slack, X). Visuel : docs/assets/img/og-bp-air.png.
JSON-LD schema.org overrides/main.html Déclare l'Organisation éditrice, le site et chaque fiche en TechArticle, avec licence, auteur et date. C'est ce que lisent Google et les assistants pour attribuer.
llms.txt + llms-full.txt générés par hooks/llms.py Index et corpus complet au format llmstxt.org, pour que les assistants citent le guide sans parcourir le site.
robots.txt docs/robots.txt Autorise explicitement les robots IA nommés (GPTBot, ClaudeBot, PerplexityBot…).
sitemap.xml généré par MkDocs Découverte des 16 pages.
CITATION.cff racine Citation académique, lue par GitHub et Zenodo.

Rien de tout cela n'est à maintenir à la main : llms.txt et llms-full.txt sont dérivés du contenu réel à chaque build, les balises du frontmatter. La seule chose à renseigner en créant une fiche, c'est description: : une phrase, dans l'entête.

11. Licence

L'ensemble du contenu de ce dépôt (fiches, guide, schémas) est publié sous licence Creative Commons Attribution / Partage dans les Mêmes Conditions 4.0 International (CC BY-SA 4.0).

Vous êtes libre de le partager et de l'adapter, y compris commercialement, à deux conditions :

  • Attribution : créditer « Institut du Numérique Responsable / ISIT, Groupe de Travail AIR » et indiquer les modifications apportées.
  • Partage dans les Mêmes Conditions : toute œuvre dérivée doit être diffusée sous la même licence.

Ce choix n'est pas arbitraire : le contenu dérive de publications INR/ISIT déjà sous CC BY-SA 4.0, dont la clause de partage à l'identique se propage aux travaux dérivés.

En contribuant à ce dépôt, vous acceptez que votre contribution soit diffusée sous cette licence.

Contenu fusionnant le Livre Blanc AIR (INR, 2024), le Guide des Bonnes Pratiques AIR (2026) et le Guide d'évaluation de la maturité NR des parties prenantes (INR/ISIT, 2024).