Contribuer à la documentation NemoClaw

Ce guide explique comment rédiger, modifier et réviser la documentation de NemoClaw. Si vous modifiez du code qui affecte le comportement visible par les utilisateurs, mettez à jour la documentation correspondante dans la même PR.

Utiliser les compétences de l’agent

Si vous utilisez un agent de programmation IA (Cursor, Claude Code, Codex, etc.), le dépôt inclut des compétences qui automatisent le travail de documentation. Utilisez-les avant de rédiger à partir de zéro.

Les compétences se trouvent dans .agents/skills/ et suivent automatiquement le guide de style ci-dessous. Pour en utiliser une, demandez à votre agent de l’exécuter. Par exemple, demandez-lui de « mettre à jour la documentation pour tout ce qui a été fusionné depuis v0.2.0 ».

Quand mettre à jour la documentation

Mettez à jour la documentation lorsque votre modification :

• Ajoute, supprime ou renomme une commande ou un drapeau CLI.
• Modifie le comportement par défaut ou la configuration.
• Ajoute une nouvelle fonctionnalité avec laquelle les utilisateurs interagissent.
• Corrige un bug que la documentation décrit incorrectement.
• Modifie une API, un protocole ou un schéma de politique.

Compiler la documentation localement

Vérifiez que la documentation est correctement compilée en la construisant et en vérifiant le résultat.

Pour compiler la documentation, exécutez :

make docs

Pour servir la documentation localement et la recompiler automatiquement lors des modifications, exécutez :

make docs-live

Conventions de rédaction

Format

• La documentation utilise MyST Markdown, un surensemble de CommonMark compatible avec Sphinx.
• Chaque page commence par un en-tête YAML (title, description, topics, tags, content type).
• Incluez l’en-tête de licence SPDX après le frontmatter.

Modèle de frontmatter

---
title:
  page: "NemoClaw Page Title — Subtitle with Context"
  nav: "Short Nav Title"
description: "One-sentence summary of the page."
keywords: ["primary keyword", "secondary keyword phrase"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "relevant", "tags"]
content:
  type: concept | how_to | get_started | tutorial | reference
  difficulty: technical_beginner | technical_intermediate | technical_advanced
  audience: ["developer", "engineer"]
status: published
---

Structure de la page

1. Titre H1 correspondant à la valeur title.page.
2. Une ou deux phrases d’introduction indiquant le sujet de la page.
3. Sections organisées par tâche ou concept, utilisant H2 et H3. Commencez chaque section par une phrase d’introduction qui oriente le lecteur.
4. Une section « Étapes suivantes » en bas de page avec des liens vers les pages connexes.

Guide de style

Rédigez comme si vous expliquiez quelque chose à un collègue. Soyez direct, précis et concis.

Voix et ton

• Utilisez la voix active. « Le CLI crée une passerelle » et non « Une passerelle est créée par le CLI. »
• Utilisez la deuxième personne (« vous ») pour vous adresser au lecteur.
• Utilisez le présent. « La commande renvoie une erreur » et non « La commande renverra une erreur. »
• Énoncez les faits. N’atténuez pas avec « simplement », « juste », « facilement » ou « bien sûr ».

Ce qu’il faut éviter

Ces motifs sont courants dans les textes générés par les LLM et nuisent à la confiance des lecteurs techniques. Supprimez-les lors de la révision.

Règles de formatage

• Terminez chaque phrase par un point.
• Une phrase par ligne dans le fichier source (pour des diffs lisibles).
• Utilisez le formatage code pour les commandes CLI, les chemins de fichiers, les drapeaux, les noms de paramètres et les valeurs.
• Utilisez des blocs de code avec le langage console pour les exemples CLI. Préfixez les commandes avec $ :

  $ nemoclaw onboard

• Utilisez des tableaux pour les comparaisons structurées. Gardez les tableaux simples (pas de formatage imbriqué).
• Utilisez des admonitions en citation (> **Note :**, > **Avertissement :**) pour les encadrés, pas du texte en gras.
• Évitez les admonitions imbriquées.
• Ne numérotez pas les titres de section. Écrivez « Déployer une passerelle » et non « Section 1 : Déployer une passerelle » ou « Étape 3 : Vérifier. »
• N’utilisez pas de deux-points dans les titres. Écrivez « Déployer et gérer les passerelles » et non « Passerelles : Déployer et gérer. »
• Utilisez les deux-points uniquement pour introduire une liste. N’utilisez pas les deux-points comme ponctuation générale entre les propositions.

Liste de mots

Utilisez-les de manière cohérente :

Soumettre des modifications de documentation

1. Créez une branche en suivant la convention du projet.
2. Effectuez vos modifications.
3. Compilez localement avec make docs et vérifiez le résultat.
4. Ouvrez une PR avec docs: comme type de commit conventionnel.

docs: update quickstart for new onboard wizard

Si votre modification de documentation accompagne une modification de code, incluez les deux dans la même PR et utilisez le type de commit de la modification de code :

feat(cli): add policy-add command

Réviser les PR de documentation

Lors de la révision de documentation :

• Vérifiez que les règles du guide de style ci-dessus sont respectées.
• Recherchez les motifs générés par les LLM (gras excessif, tirets cadratins, remplissage).
• Vérifiez que les exemples de code sont exacts et exécutables.
• Confirmez que les références croisées et les liens ne sont pas cassés.
• Compilez localement pour vérifier le rendu.