🧭 Guide de Méthode : Réussir la Doc d'OctopiaSync

Ce fichier n'est pas un exemple de contenu, mais un guide stratégique rédigé en Markdown. Il vous explique comment concevoir, structurer et rédiger la documentation technique d'OctopiaSync pour qu'elle soit professionnelle, claire et adoptée par les utilisateurs.

🛑 Les 3 Commandements du Rédacteur

Avant d'écrire une seule ligne de Markdown, gardez ceci en tête :

Pensez "Utilisateur", pas "Code" : L'utilisateur se fiche de savoir comment votre PHP est structuré. Il veut savoir : "Comment j'appuie sur ce bouton pour que mon stock soit à jour sur Octopia ?".
Soyez Actionnable : Une bonne page de doc doit toujours se terminer par une action claire (ex: "Maintenant, passez au mapping").
L'Image est Reine : Une capture d'écran avec un cercle rouge autour du bouton à cliquer vaut 10 paragraphes de texte.

🏗️ Structure Type d'une Documentation SaaS

Une documentation professionnelle doit suivre un parcours logique. Voici la structure recommandée pour OctopiaSync dans votre fichier mkdocs.yml :

nav:
  - Accueil: index.md              # La vision globale, pré-requis.
  - 🚀 Démarrage Rapide:
    - Installation: install.md     # Comment mettre le module sur PS.
    - Connexion API: api.md        # Authentification.
  - ⚙️ Configuration Core:
    - Mapping Catégories: mapping.md # Étape CRITIQUE.
    - Gestion Stocks & Prix: stock.md # Règles métier.
  - 🔄 Automatisation:
    - Tâches Cron: cron.md         # Synchronisation automatique.
  - 📦 Gestion Quotidienne:
    - Traitement Commandes: orders.md # Comment gérer le SAV/Envoi.
  - 🛠️ Résolution de Problèmes:
    - Logs & Erreurs: debug.md     # Guide de dépannage.

✍️ Rédiger une Page : La Méthode "B.A.R."

Pour chaque page technique, suivez la méthode B.A.R. (Bénéfice, Action, Risque).

B - Bénéfice (Pourquoi lire cette page ?)

Dès l'introduction, expliquez ce que l'utilisateur gagne à configurer cette partie.

Exemple : "Le mapping des catégories permet de classer automatiquement vos produits PrestaShop dans les bonnes rayons d'Octopia, garantissant leur visibilité."

A - Action (Comment faire ?)

Utilisez des listes numérotées et des blocs de code pour détailler les étapes.

Exemple : "1. Allez dans l'onglet Mapping. 2. Cliquez sur 'Associer'."

R - Risque (Que vérifier ?)

Utilisez les admonitions pour signaler les erreurs communes.

Exemple : "!!! danger 'Attention' Ne mappez pas une catégorie PrestaShop vide."

🛠️ Outils Markdown à Maîtriser

MkDocs Material offre des outils puissants. Vous devez les utiliser pour rythmer votre lecture.

1. Les Admonitions (Alerte visuelle)

!!! info "Conseil"
    Utilisez ceci pour une bonne pratique.

!!! warning "Vigilance"
    Utilisez ceci pour éviter un bug mineur.

!!! danger "Critique"
    Utilisez ceci pour une action irréversible (suppression).

2. Les Onglets (Tabs)

Indispensables pour comparer des versions ou des méthodes d'installation.

=== "PrestaShop 1.7"
    Instructions PS 1.7...

=== "PrestaShop 8.x"
    Instructions PS 8...

3. Les Tableaux

La seule manière propre de lister des pré-requis ou des définitions de paramètres.

| Paramètre | Description | Type |
| :--- | :--- | :---: |
| `API_KEY` | Votre clé secrète Octopia. | *String* |

📐 Check-list de Finition d'une Page

Avant de considérer une page comme "terminée", vérifiez :

[ ] Pas de Jargon Non Expliqué : Si vous utilisez "Cron", expliquez brièvement que c'est un planificateur de tâches.
[ ] Une Capture d'Écran : Au moins une image par grande section.
[ ] Un CTA (Call To Action) : Un bouton à la fin vers la page suivante.
[ ] Les Liens Internes : Avez-vous fait un lien vers la page "Dépannage" s'il y a un risque d'erreur commun ?

🆘 Comment Dépanner la Doc

Problème	Cause Commune	Solution
Rendu cassé	Ligne vide manquante	Ajoutez une ligne vide entre le texte et l'élément (tableau, liste).
Onglet vide	Mauvaise indentation	Décalez tout le contenu de l'onglet de 4 espaces ou 1 tab.
Icône invisible	Extension manquante	Vérifiez que `pymdownx.emoji` est activé dans `mkdocs.yml`.