provider-docs

Aperçu du skill provider-docs

Ce que fait provider-docs

Le skill provider-docs vous aide à créer, mettre à jour et vérifier la documentation Terraform Registry pour les providers Terraform. Il est conçu pour les auteurs de providers et les rédacteurs techniques qui ont besoin d’une documentation exacte, basée sur les descriptions de schéma et les templates tfplugindocs, pas d’une simple réécriture de prose générique.

Pour qui il est le plus adapté

Utilisez le skill provider-docs lorsque vous modifiez le comportement d’un provider et que la documentation doit rester synchronisée : configuration du provider, resources, data sources, ephemeral resources, list resources, functions ou guides. Il est particulièrement utile dans les workflows de Technical Writing où la source de vérité combine le code et la sortie Registry générée.

En quoi il se distingue

Ce skill est optimisé pour la structure attendue par HashiCorp : détails des champs pilotés par le schéma, fichiers de template dans la structure docs/ prévue, et publication Registry tenant compte des releases. Sa valeur principale est de réduire les approximations sur ce qui doit être écrit dans le code ou dans les templates, et sur la façon de garder une documentation générée publiable.

Comment utiliser le skill provider-docs

Installer et charger les bons fichiers

Installez-le avec npx skills add hashicorp/agent-skills --skill provider-docs. Pour disposer du contexte initial, lisez SKILL.md, references/hashicorp-provider-docs.md et agents/openai.yaml. Si l’organisation du dépôt n’est pas claire, inspectez d’abord les dossiers agents/ et references/ avant de modifier quoi que ce soit.

Transformer une demande vague en prompt exploitable

L’étape provider-docs install n’est qu’un point de départ ; le skill donne les meilleurs résultats quand votre prompt nomme précisément les objets Terraform et la sortie documentaire attendue. Par exemple : « Mettre à jour l’usage de provider-docs pour la resource foo et la data source bar après l’ajout d’un nouvel argument timeout ; s’assurer que les descriptions du schéma et les exemples dans docs/*.md.tmpl correspondent à l’implémentation. » C’est bien mieux que « écrire la doc », parce que le skill peut faire le lien entre les changements de code et les cibles Registry précises.

Suivre un workflow centré d’abord sur le dépôt

Commencez par les descriptions du schéma, puis mettez à jour les fichiers template correspondants dans docs/, puis générez la documentation avec tfplugindocs. Préférez go generate ./... si le dépôt orchestre la génération de cette manière. Cet ordre est important, car les pages Registry générées dépendent d’un texte de schéma précis avant que les templates soient finalisés.

Ce qu’il faut vérifier avant la publication

Vérifiez que chaque chemin de template correspond à un véritable objet du provider : docs/index.md.tmpl, docs/resources/<name>.md.tmpl, docs/data-sources/<name>.md.tmpl, docs/ephemeral-resources/<name>.md.tmpl, docs/list-resources/<name>.md.tmpl, docs/functions/<name>.md.tmpl ou docs/guides/<name>.md.tmpl. Confirmez aussi que les tags de release utilisent la sémantique v et que terraform-registry-manifest.json est valide, car le rendu Registry dépend de ces deux éléments.

FAQ sur le skill provider-docs

provider-docs sert-il seulement à la documentation générée ?

Dans la plupart des cas, oui. Le skill provider-docs est particulièrement efficace quand la documentation est produite à partir des descriptions de schéma et des templates. Si vous devez rédiger une page marketing ponctuelle ou un texte produit plus général, un prompt classique sera souvent plus adapté.

Faut-il être expert Terraform ?

Pas nécessairement, mais il faut connaître les noms des objets du provider et les changements de code qui pilotent la documentation. Le skill reste accessible pour les mises à jour de docs, à condition de l’orienter vers la bonne resource, data source ou function.

Quand vaut-il mieux ne pas l’utiliser ?

N’utilisez pas provider-docs pour une documentation sans lien avec la sortie Terraform Registry, ni lorsque l’implémentation du provider est encore instable et que le schéma va changer immédiatement à nouveau. Dans ces cas, attendez que l’interface se stabilise, puis générez le guide provider-docs à partir de la forme finale.

En quoi se compare-t-il à un prompt générique ?

Un prompt générique peut rédiger du texte, mais provider-docs conserve mieux le workflow Registry, l’organisation des fichiers et les contraintes de release qui permettent réellement de publier la documentation d’un provider. Cela réduit les retouches quand on passe d’un brouillon à la sortie de tfplugindocs.

Comment améliorer le skill provider-docs

Donnez-lui des faits d’implémentation, pas seulement des objectifs

La meilleure utilisation de provider-docs commence avec des entrées concrètes : quel objet du provider a changé, quelle est la nouvelle argumentation ou le nouveau comportement, si les valeurs par défaut ou calculées ont changé, et quel exemple doit être mis à jour. « Ajouter un champ retry_count avec une valeur par défaut de 3 et le documenter dans la resource foo » est bien plus utile que « améliorer la doc ».

Surveillez le mode d’échec le plus courant

Le principal risque consiste à écrire une prose de template qui sonne juste mais ne correspond pas au comportement du schéma. Si un champ est requis, optionnel, calculé ou défini conditionnellement, dites-le explicitement dans la description du schéma et dans le contexte de l’exemple. C’est cet alignement qui rend la documentation générée fiable.

Itérez à partir de la sortie générée

Après le premier passage, examinez l’aperçu Registry rendu et comparez-le au code du provider, pas seulement au fichier template. Si le libellé est vague, resserrez d’abord la description du schéma ; si l’exemple prête à confusion, ajustez le template ; s’il manque une section, vérifiez le chemin docs/ et les noms d’objets avant de réécrire le contenu.