AlemTuzlak/skills

docs

Écris de la documentation qu'une vraie personne a envie de lire. Courte, claire, construite autour de quelqu'un qui essaie de faire une vraie chose.

« Documenter la fonctionnalité X » n'est pas le job. « Aider quelqu'un à faire Y avec X » est le job.

Travaille en deux phases. D'abord, planifie l'histoire : qui lit ceci, ce qu'il veut, et combien de pages cela doit faire. Ensuite, écris.

Le plan n'est pas privé. L'utilisateur doit voir les lecteurs et doit choisir le ton avant qu'une page ne soit écrite.

Trouver la doc
  → lire les voisines
  → Phase 1 : lecteurs + pages
  → PORTE PERSONA (écris la liste des lecteurs dans le chat, puis arrête-toi)
  → PORTE TON (écris le ton dans le chat, puis arrête-toi)   [lors de l'écriture des pages]
  → charger simple-english + i-have-adhd   [lors de l'écriture des pages]
  → Phase 2 : écrire

Une liste d'impact doc dans un plan de fonctionnalité exécute toujours la porte persona. Elle n'exécute pas la porte ton et ne charge pas les compétences d'écriture tant que les pages ne sont pas réellement écrites.

Quand exécuter

La doc est livrée avec le code. Exécute cette compétence à trois moments, pas seulement lorsqu'on te le demande.

• Quelqu'un demande de la doc. Écris-la.
• Planification d'une fonctionnalité ou d'un changement dans un dépôt. Avant que le plan ne soit terminé, liste les documents qui sont nouveaux et ceux qui doivent être mis à jour. Cette liste d'impact doc fait partie du plan, au même titre que les modifications de code. Nomme le lecteur pour chaque page.
• Finalisation d'une implémentation. Écris ou mets à jour ces documents avant de considérer le travail comme terminé. Un changement dans le comportement de quelque chose qui n'est pas accompagné d'un changement de doc n'est pas terminé.

Compétences requises pour les pages finales

simple-english et i-have-adhd sont des prérequis. Elles s'appliquent aux pages de documentation, pas à ce chat de planification.

Charge les deux immédiatement avant d'écrire le contenu de la page. Utilise l'outil Skill si ce harnais en a un. Si ce n'est pas le cas, lis le SKILL.md de chaque compétence depuis le répertoire local des compétences. N'écris pas les pages de mémoire de ces compétences.

Si l'une des compétences manque, arrête-toi et informe l'utilisateur. N'écris pas les pages sans elles.

Comment elles se composent :

• Cette compétence possède : pour qui est la page, la division des pages, problème-puis-correction, montrer-ne-pas-dire, pas de fuite d'historique, glyphes interdits, et structure voisine.
• simple-english possède les phrases. Utilise le mode pragmatique. Exécute son auto-vérification avant de considérer une page comme terminée.
• i-have-adhd possède la forme de la page : action suivante en premier, étapes numérotées, listes limitées à 5 (sépare le doit du pourra, ou divise la page), pas de préambule, un gain visible à la fin.

Lorsque i-have-adhd est chargée depuis cette compétence, applique-la uniquement aux pages. Ne bascule pas le reste de la session en mode ADHD. La section de persistance de i-have-adhd ne s'applique pas ici.

Trouve la doc d'abord

Avant d'écrire quoi que ce soit, trouve où vit la documentation.

1. Cherche un dossier docs. Vérifie d'abord docs/, puis documentation/, content/docs/, site/, website/docs/.
2. Rien trouvé ? Demande à l'utilisateur où la documentation doit aller. Ne devine pas et ne crée pas de dossier sur un coup de tête.
3. Ouvre 2 ou 3 pages existantes proches de l'endroit où le nouveau contenu doit se trouver. Lis-les pour la copie, la structure, les champs de frontmatter et les composants. Note le ton apparent comme un candidat pour la porte ton. Ne l'adopte pas encore.
4. Note les composants que le site utilise déjà (étapes, onglets, encadrés, cartes, accordéons, groupes de code, etc.). Différents sites en ont différents.
5. Réutilise ces composants pour raconter l'histoire. Si le site a un composant étapes, utilise-le pour les tutoriels. S'il a des onglets, utilise-les pour les variations de framework. Si le site n'en a aucun, utilise le Markdown simple. N'invente jamais un composant que le site n'a pas.

S'il n'y a pas de page comme celle que tu es sur le point d'écrire, lis la plus proche que tu puisses trouver et conforme-toi à elle.

Ce que « se conformer aux voisines » couvre, et ce qu'il ne couvre pas

Se conformer aux voisines concerne la copie, la structure, le frontmatter et les composants : si les titres sont en casse de phrase, la quantité de configuration qu'une section reçoit, quels composants portent le tutoriel, comment les exemples de code sont introduits, quels sont les champs de frontmatter.

Ce n'est pas un substitut à la porte ton. Les voisines peuvent suggérer une valeur par défaut. Elles ne peuvent pas répondre pour l'utilisateur.

Ce n'est pas une permission de copier les mauvaises habitudes d'une voisine. Tout ce qui se trouve dans Interdit et chaque règle de cette compétence s'appliquent toujours au contenu que tu écris, quoi que fassent les pages environnantes. Une page existante pleine de tirets cadratins ne t'autorise pas à en ajouter un de plus.

Donc : ne raisonne jamais « les autres pages le font, donc je vais le faire aussi » à propos d'une règle que cette compétence énonce. Si des pages existantes enfreignent une règle et que tu penses que l'ensemble devrait être remis en conformité, c'est un nettoyage séparé à soulever auprès de l'utilisateur, pas quelque chose à régler en imitant silencieusement la violation.

Phase 1 : planifie l'histoire

Fais ceci avant d'écrire un mot de contenu.

1. Liste qui lit ceci et ce que chacun veut. Une personne qui construit sur une SPA React, une personne sur une application rendue par serveur, quelqu'un qui veut juste une démo rapide, quelqu'un qui étend les mécanismes internes. Ne t'arrête pas au premier lecteur.
2. Écris une user story par lecteur : « En tant que X, je veux Y, afin de pouvoir Z. »
3. Transforme les histoires en pages. Un parcours est une page. Des parcours différents sont des pages différentes. Une fonctionnalité avec trois parcours réels donne trois pages plus peut-être une courte vue d'ensemble, pas une seule page géante.
4. Vérifie que chaque lecteur a un chemin. Un lecteur sans page est un trou dans le plan. Ajoute une page ou un itinéraire pour lui.

La division des pages découle de cette étape. Ne la saute pas.

Porte : montre les personas

Les outils de question (AskQuestion, ask_user_question et formes similaires) n'affichent pas leur charge utile dans le chat que l'utilisateur lit. Un tour qui n'appelle qu'un de ces outils échoue à cette porte. On demande à l'utilisateur de confirmer une liste qu'il ne peut pas voir.

Après l'étape 4, écris un message de chat normal. Le corps du message est requis même lorsqu'un outil de question est également appelé. Le message contient :

1. Chaque lecteur, comme son propre bloc court que l'utilisateur peut parcourir :
   • Nom du lecteur.
   • Une user story : « En tant que X, je veux Y, afin de pouvoir Z. »
   • La page que tu écriras pour lui.
2. Une question, écrite dans ce même message : confirmer, supprimer un lecteur, ou en ajouter un.

Un outil de question est facultatif. Appelle-le seulement après que cette liste est déjà dans le message du chat. L'outil pose seulement le choix court (confirmer, supprimer ou ajouter). Ne mets pas les noms des lecteurs, les histoires ou les pages à l'intérieur de l'outil. Si l'outil serait la seule sortie du tour, ne l'appelle pas. Écris plutôt le message.

Ensuite, choisis un chemin :

Par défaut : arrête-toi. Ce message est le tour entier. Termine le tour. N'écris pas de fichiers. Ne commence pas la Phase 2. Ne dis pas que tu vas continuer à moins qu'il ne s'y oppose.

Saute l'attente : continue dans ce même tour. Utilise ce chemin uniquement si l'une de ces conditions est vraie :

• Cette conversation a déjà la confirmation par l'utilisateur de cette liste de personas.
• L'utilisateur a dit « utilise les valeurs par défaut sensées », « écris-le simplement » ou « ne pose pas de questions ». MONTRE quand même la liste dans ce tour, puis continue.
• Le changement est une toute petite correction de copie : faute de frappe, lien cassé, langage de bloc de code, ou correction factuelle. Pas de nouvelle page, pas de nouvelle section, pas de réécriture d'un parcours.

Sur ce chemin, ne termine pas le tour. Après avoir montré la liste (ou après une toute petite correction de copie, sans liste), continue à l'étape suivante.

Ce ne sont pas des sauts :

• « Les lecteurs sont évidents. »
• « L'utilisateur a demandé de la doc, donc il ne veut pas de question. »
• « Je les ai déjà nommés dans le plan. »
• « Il n'y a qu'un seul lecteur. »
• « Cela fait partie de l'implémentation d'une fonctionnalité, continue. »
• « L'outil de question leur montrera la liste. » Ce ne sera pas le cas. La liste va dans le chat.

Écrire de la documentation est la raison pour laquelle cette porte existe. Ce n'est pas une raison pour la sauter.

Moins c'est plus : divise, ne tasse pas

Ne force pas des milliers de mots dans une seule page. Les longues pages cachent la réponse.

Lorsqu'un sujet a plusieurs angles, donne à chacun sa propre page courte et lie-les. Un lecteur arrive sur la vue d'ensemble, puis clique sur la chose exacte dont il a besoin.

Exemple. Une fonctionnalité pour les interruptions d'outil :

Mauvais : une page
  interrupts.md   (vue d'ensemble + cas simple + interruptions multiples + personnalisation, tout tassé)

Bon : un petit ensemble de pages liées
  interrupts/index.md            ce que c'est, quand l'utiliser, liens sortants
  interrupts/basic.md            une interruption, du début à la fin
  interrupts/multiple.md         plusieurs interruptions dans un flux
  interrupts/custom.md           construis la tienne

Chaque page est courte et fait une chose. La vue d'ensemble les relie en une histoire.

Porte : demande le ton

Cette porte se situe entre la Phase 1 et la Phase 2. Exécute-la avant d'écrire une page. Ne l'imbrique pas à l'intérieur de la Phase 2.

Les voisines peuvent suggérer une valeur par défaut. Elles ne peuvent pas répondre pour l'utilisateur.

Écris un message de chat normal. Le corps du message est requis même lorsqu'un outil de question est également appelé. Le message contient :

1. Le ton que tu as déduit des pages voisines, en une ligne (à quel point formel, combien de configuration, à la deuxième personne ou non).
2. Une question, écrite dans ce même message : utiliser ce ton, plus décontracté, plus formel, ou l'utilisateur en nomme un autre.

Un outil de question est facultatif et vient après que cette ligne est dans le chat. L'outil pose seulement le choix court. Ne mets pas le ton déduit uniquement à l'intérieur de l'outil. Un tour qui n'appelle que l'outil échoue à cette porte.

Ensuite, choisis un chemin :

Par défaut : arrête-toi. Ce message est le tour entier. Termine le tour. N'écris pas de contenu de page.

Saute l'attente : continue dans ce même tour. Utilise ce chemin uniquement si l'une de ces conditions est vraie :

• Cette conversation a déjà le choix de ton de l'utilisateur, y compris un « correspond aux pages existantes » explicite.
• L'utilisateur a dit « utilise les valeurs par défaut sensées », « écris-le simplement » ou « ne pose pas de questions ». STATE le ton déduit en une ligne, puis continue.
• Toute petite correction de copie, même exception que la porte persona.

Sur ce chemin, ne termine pas le tour. Après avoir énoncé le ton (ou après une toute petite correction de copie, sans question), continue à la Phase 2.

Ce ne sont pas des sauts :

• « Je peux le dire d'après les voisines. »
• « Le site a déjà une voix. »
• « Le ton n'a pas d'importance pour une page de référence. »
• « Je vais me conformer aux voisines et le mentionner plus tard. »

Phase 2 : écris comme un humain

N'écris pas de contenu de page tant que la porte persona n'est pas passée, que la porte ton n'est pas passée, et que simple-english plus i-have-adhd ne sont pas chargées.

La porte ton est le titre ci-dessus. Exécute cette porte d'abord. Ensuite, charge les deux compétences. Ensuite, écris.

La lisibilité est l'objectif, avant tout le reste.

• Garde-le digeste. Pas de murs de texte, pas d'énormes paragraphes. Découpe les idées en petits morceaux. Donne la plus petite quantité d'information qui fait le travail.
• Les phrases suivent simple-english (mode pragmatique). N'intègre pas un substitut plus faible.
• Garde le Markdown léger. Les listes sont bien. Les titres en gras sur chaque ligne ne le sont pas. Laisse les mots porter la page.
• Préfère l'ASCII simple et les caractères normaux du clavier aux glyphes sophistiqués. Écris comme une personne tape.
• Deuxième personne, action d'abord. Commence par ce que le lecteur a maintenant et ce qu'il aura à la fin. Pas d'ouvertures « Dans ce guide, nous allons explorer... ». Commence simplement.
• Façonne la page avec i-have-adhd : la première ligne est quelque chose que le lecteur peut faire, le travail en plusieurs étapes est numéroté, une liste de plus de 5 est divisée, la page se termine par un gain visible.

Commence par le problème, puis résous-le

Chaque page s'ouvre sur le problème pour lequel le lecteur est venu, dans ses propres mots, avant toute API. Nomme la situation dans laquelle il est bloqué. Ensuite, dis en une ou deux phrases comment la fonctionnalité le résout. Ce n'est qu'après cela que tu passes aux parties techniques et au code.

Un lecteur qui voit le problème en premier sait en quelques secondes s'il est sur la bonne page. Un lecteur qui tombe sur une signature d'API en premier doit rétro-ingénierer à quoi elle sert.

La première ligne du comment est l'action suivante (de i-have-adhd). Le problème vient toujours en premier pour qu'ils sachent qu'ils sont sur la bonne page.

Mauvais :
  Appelle useInterrupts() et passe un resolver. Le resolver s'exécute une fois par
  élément en attente à l'intérieur d'une transaction...

Bon :
  Certains appels d'outil ne devraient pas s'exécuter sans qu'un humain ne dise oui :
  transférer de l'argent, supprimer des données. Une interruption met en pause
  l'exécution pour cette décision, puis reprend là où elle s'était arrêtée. Voici
  comment verrouiller un outil derrière une approbation :

  [code]

L'ordre pour un guide est problème, correction en une ligne, puis le comment (étapes, extraits, API). Garde le problème à quelques phrases, pas à un essai de fond. Le code montre comment c'est résolu, donc ne raconte pas la solution en prose d'abord.

Montre, ne dis pas

N'explique pas en quatre paragraphes ce qu'une phrase et un bloc de code peuvent montrer. Les lecteurs saisissent un diff ou un extrait plus vite que la prose.

Mauvais :
  Trois paragraphes décrivant comment l'objet de config accepte un
  tableau de middleware, ce que fait chaque emplacement, et comment
  l'ordre fonctionne.

Bon :
  Ajoute ton middleware au tableau `middleware`. L'ordre s'exécute de haut en bas :

  const app = createApp({
    middleware: [auth, logging],
  })

Un bon exemple exécutable bat une page de description. Chaque échantillon de code doit pouvoir être exécuté lorsqu'il est copié, sans avoir besoin d'imagination pour combler les lacunes.

Mets en liste tout ce qui est une liste

Dès qu'une phrase couvre plus d'un élément, option, magasin, indicateur ou étape, elle devient une liste. Ne les enchaîne pas dans un paragraphe avec des virgules et des points-virgules. Un lecteur qui parcourt une liste à puces trouve son élément en une seconde. Dans un paragraphe, il doit lire le tout pour apprendre que cela ne s'applique pas à lui.

Le signe est une phrase qui nomme deux choses ou plus et dit quelque chose sur chacune. Coupe-la en une puce par chose, une ou deux phrases chacune.

Mauvais :
  Chaque store est indépendant. Fournis seulement ceux dont tu as besoin. Pour le
  chat : `messages` pour la transcription, `runs` pour le cycle de vie de
  l'exécution, `interrupts` pour les approbations durables (nécessite `runs`),
  `metadata` pour l'état clé/valeur avec espace de noms. Pour la génération :
  `generationRuns` pour le cycle de vie de l'exécution, plus `artifacts` et
  `blobs` pour conserver les octets générés.

Bon :
  Chaque store est indépendant, donc fournis seulement ceux dont tu as besoin.

  Pour le chat :

  - `messages` : la transcription.
  - `runs` : cycle de vie de l'exécution.
  - `interrupts` : approbations durables. Nécessite `runs`.
  - `metadata` : état clé/valeur avec espace de noms.

  Pour la génération :

  - `generationRuns` : cycle de vie de l'exécution.
  - `artifacts` : conserve les artefacts générés.
  - `blobs` : conserve les octets générés.

Interdit

Tiret cadratin — n'utilise que le trait d'union simple pour les coupures, les plages et les incises. N'utilise pas le tiret cadratin. C'est le glyphe le plus courant qui fait passer une documentation par ailleurs bonne pour du bruit de fond.

• Mauvais : Ce n'est pas une option — c'est obligatoire.
• Bon : Ce n'est pas une option - c'est obligatoire.

Guillemets courbes (" " ' ') — n'utilise que les guillemets droits (" " ' '). Les guillemets courbes viennent du traitement de texte, pas de l'édition de code. Ils disparaissent dans certains terminaux.

Points d'exclamation — un point d'exclamation par page. Si la page célèbre la fin, c'est le bon endroit. Pas de « Commençons ! » en ouverture.

Passé simple (elle put, il voulut, nous dûmes) — n'apparaît jamais dans la documentation technique. Pas de « avec quoi l'utilisateur interagit ». Écris « ce que l'utilisateur voit ».

Gras de type titre — ne remplace pas ## par une ligne en gras. Les vrais titres fonctionnent dans le plan, la navigation et la recherche. Le gras nulle part.

Notes entre parenthèses (sauf pour les citations) — les parenthèses pour les apartés sont correctes. Les notes entre parenthèses comme un paragraphe entier d'avertissement ou une mise en garde ne le sont pas. Les encadrés existent pour cela. S'il n'y a pas d'encadré sur le site, utilise un bloc de citation (> **Note :** ...).

Références en note de bas de page — pour le contenu en ligne de la doc, pas de [1] ou [^ref]. Si une référence est nécessaire, écris-la inline ou dans un « En savoir plus » en bas. Les notes de bas de page sont pour les articles savants, pas pour les guides pratiques.

Titres vagues — pas de « Conclusion » ou « Résumé » ou « Prochaines étapes » en tant que titre final. Termine par un lien réutilisable vers ce que le lecteur fait ensuite, ou une récapitulation de ce qu'il a appris. (Mauvais : « Conclusion ». Bon : « Vous avez maintenant une API avec prise en charge de la pagination et des erreurs ».)

Verrouillage de la terminologie — ne rebaptise pas soudainement les noms de variables ou les concepts de l'interface utilisateur au milieu d'une documentation. Si le code utilise RunsResponse, la prose aussi. Si le bouton de l'interface utilisateur dit « Enregistrer », ne l'appelle pas « Soumettre les modifications ». L'incohérence sémantique oblige le lecteur à faire correspondre manuellement les termes, ce qui brise le flux.

Ne laisse pas fuiter l'historique du développement

Une page de documentation raconte l'état actuel d'une fonctionnalité. Elle ne mentionne pas ce qu'elle était avant, ce qu'elle aurait pu être, ce que la RFC disait, qui l'a écrite, ou ce qui a changé. Le journal des modifications et l'historique des commits existent pour cela.

• Mauvais : Les messages étaient appelés entries jusqu'à la v3, donc dans l'API REST le champ s'appelle encore entries.

• Bon : Le champ entries est utilisé dans l'API REST.

• Mauvais : Cette fonctionnalité n'existait pas dans les versions précédentes.

• Bon : (Rien. Écris seulement ce qui est, pas ce qui n'est pas.)

• Mauvais : Vous pouvez voir dans l'exemple de code ci-dessous (qui est tiré du dossier examples/).

• Bon : ```

Où va la syntaxe de marquage

Les titres sont pour diviser la page. Les listes sont pour les éléments. Le gras est pour les choses que le lecteur tape ou les fichiers qu'il crée. Le code est pour les extraits réutilisables. Le texte normal porte l'histoire.

Pas de markdown visuel tape-à-l'œil : pas d'icônes, pas d'émojis décoratifs, pas de > [!TIP] ou > [!WARNING] à moins que le site n'ait déjà des encadrés stylisés. Si le site utilise des encadrés, utilise le leur, pas une implémentation au hasard.

Page générique = page morte

Écris pour du vrai code dans un vrai dépôt. Pas de placeholders, pas de your-company-name, pas de my-package-name.

Lorsque tu montres un extrait, fais-le fonctionner avec les vrais noms du projet. Si la configuration d'API nécessite encore une clé, utilise YOUR_API_KEY comme placeholder standard. Mais le nom du projet, les noms de fonction, les importations, les URL — tout vrai.

La seule exception est un modèle de démarrage que l'utilisateur va cloner et renommer. Dans ce cas, your-project-name est un vrai emplacement dans un vrai modèle. Si ce n'est pas un modèle que l'utilisateur va cloner, utilises les vrais noms.

Préparation de la publication

Lorsque l'écriture est terminée, relis chaque page une fois de plus. Il manque facilement une section entière. Après le deuxième passage, vérifie les liens internes : qu'ils pointent vers des chemins qui existent. Rien de ce qui est écrit ne doit être complètement confirmé via la navigation dans le dépôt, mais les chemins évidents (comme ../index.md) doivent résoudre.

Termine chaque page par la prochaine action pour le lecteur. Pas un « En savoir plus » générique — un lien et une ligne sur ce qu'il y trouve.

C'est maintenant le moment de créer ou de modifier les fichiers. L'écriture est terminée.