samykabu/user-manual

Manuel d'utilisation

Maintenez une source unique de contenu en Markdown, fondée sur des preuves, dans le dossier User-Manual/. Publiez trois éditions : Utilisateur final, Administrateur/exploitant et Référence technique. Le Markdown est le produit ; le rendu est une étape distincte et remplaçable.

Choisissez le workflow le plus court

• Nouveau manuel : interrogez l'utilisateur, inspectez le dépôt, proposez un plan de modules, obtenez l'approbation, puis exécutez scripts/init_manual.py avec un fichier JSON de modules approuvé.
• Manuel existant : lisez User-Manual/manual.yml, inspectez la portée demandée et le diff Git pertinent, puis mettez à jour uniquement les pages et ressources affectées.
• Audit de couverture : exécutez scripts/audit_manual.py et expliquez chaque erreur et avertissement.
• Construction : exécutez scripts/build_manual.py uniquement après la réussite de l'audit. Il assemble chaque édition, puis effectue le rendu avec renderer.kind dans manual.yml : markdown (par défaut), command ou mkdocs.
• Fraîcheur : scripts/manual_state.py record --feature <dir> après une mise à jour ; status se termine avec le code 1 lorsque les entrées ou les sorties du manuel ont changé depuis l'enregistrement.

init_manual.py copie les scripts de construction, d'audit et d'état (ainsi que les feuilles de style livrées, dans tools/theme/) vers User-Manual/tools/ pour l'IC. Après avoir mis à niveau cette compétence, actualisez ces copies à partir de son répertoire scripts/. --no-tools ignore les copies lorsque l'IC exécute les scripts depuis un autre emplacement. Les workflows d'IC suivent le mappage ci: dans --ci-policy <file>, ou dans .specify/workflow.yml lorsqu'il existe.

Cette compétence ne nécessite pas .specify/, une spécification de fonctionnalité, ni aucune commande Spec Kit. Définissez la portée du travail à partir de la demande de l'utilisateur, des preuves du dépôt et des modifications du contrôle de version.

Aiguillez uniquement ce qui est nécessaire

Tâche	Lire
Découverte et interview	discovery.md
Structure des pages et syntaxe Markdown	content-model.md
Public et langue	audience-language.md
Modifications incrémentielles	incremental-update.md
Entités, colonnes, énumérations, diagrammes ER	data-reference.md
Moteurs de rendu, modèles, marque, HTML, PDF, RTL	publishing.md
Documentation API	api-docs.md
Notes de version et guides de migration	release-docs.md
Captures d'écran de l'interface utilisateur	ui-screenshots.md
Prévisualisations et publication de versions	preview-publishing.md

Règles non négociables

1. Exiger l'anglais. L'arabe est facultatif par projet, mais les pages, les moteurs de rendu, les diagrammes et les PDF doivent prendre en charge le RTL dès l'initialisation.
2. Utilisez un anglais ou un arabe simple et naturel. Écrivez pour le public déclaré ; ne réutilisez jamais une explication technique inchangée pour un utilisateur final.
3. Basez les affirmations sur l'implémentation, les contrats, les tests, le comportement observé, les schémas ou les sources d'infrastructure approuvées. Signalez les inconnues et n'inventez jamais de comportement.
4. N'incluez jamais de secrets, d'identifiants, de jetons, de clés privées, de chaînes de connexion, d'enregistrements de production ou de données personnelles non expurgées. Utilisez des exemples synthétiques déterministes.
5. Stockez le plan de modules approuvé et extensible dans User-Manual/manual.yml. Ajoutez les découvertes ultérieures comme proposed jusqu'à approbation.
6. Gardez le Markdown canonique et écrivez la syntaxe propre à GitHub, afin que chaque page soit lisible correctement sur GitHub ; la construction le traduit pour d'autres moteurs de rendu. Générez d'autres formats uniquement via la construction.
7. Générez uniquement des diagrammes utiles, avec la compétence illustrate lorsqu'elle est installée. Gardez les aperçus système séparés des détails lisibles au niveau des modules : un aperçu ER système plus de petits diagrammes ER de modules. Documentez chaque entité, colonne, type de données, relation, contrainte et énumération mis en évidence.
8. Préservez le contenu rédigé à la main en dehors des marqueurs détenus et faites converger les réexécutions.
9. Liez une page uniquement aux pages que son public reçoit. La construction rejette les liens de page entre publics et les ressources manquantes, et ne met en scène que les ressources que les pages d'une édition atteignent, de sorte qu'un public n'expédie jamais les captures d'écran ou les échantillons d'un autre.

Exemple concret

Pour « Créez un manuel pour notre plateforme de réservation », identifiez les modules de réservation, client, paiement et opérations à partir des routes, de la navigation, des API, des tests et des fichiers de schéma. Demandez à l'utilisateur d'approuver ce plan de modules. Créez ensuite des tutoriels adaptés au public, des captures d'écran sécurisées, des références API et de données, du contenu en anglais et du contenu en arabe (optionnel) dans User-Manual/, et effectuez le rendu de la manière choisie par le projet : Markdown sur GitHub, le modèle Word de l'équipe via Pandoc, ou un site MkDocs avec des PDF.