Contribuire alla Documentazione di NemoClaw

Questa guida spiega come scrivere, modificare e revisionare la documentazione di NemoClaw. Se modifichi codice che influisce sul comportamento visibile all’utente, aggiorna la documentazione pertinente nella stessa PR.

Usa le Competenze dell’Agente

Se utilizzi un agente di coding AI (Cursor, Claude Code, Codex, ecc.), il repository include competenze che automatizzano il lavoro sulla documentazione. Usale prima di scrivere da zero.

Competenza	Cosa fa	Quando usarla
`update-docs`	Analizza i commit recenti per individuare modifiche visibili all’utente e prepara bozze di aggiornamenti alla documentazione.	Dopo l’integrazione di funzionalità, prima di un rilascio, o per trovare lacune nella documentazione.

Le competenze si trovano in .agents/skills/ e seguono automaticamente la guida di stile riportata di seguito. Per usarne una, chiedi al tuo agente di eseguirla. Ad esempio, chiedigli di “aggiornare la documentazione per tutto ciò che è stato integrato dalla v0.2.0”.

Quando Aggiornare la Documentazione

Aggiorna la documentazione quando la tua modifica:

Aggiunge, rimuove o rinomina un comando o flag della CLI.
Cambia il comportamento predefinito o la configurazione.
Aggiunge una nuova funzionalità con cui gli utenti interagiscono.
Corregge un bug descritto in modo errato nella documentazione.
Modifica un’API, un protocollo o uno schema di policy.

Compilare la Documentazione in Locale

Verifica che la documentazione sia compilata correttamente compilandola e controllando l’output.

Per compilare la documentazione, esegui:

make docs

Per servire la documentazione in locale e ricompilarla automaticamente ad ogni modifica, esegui:

make docs-live

Convenzioni di Scrittura

Formato

La documentazione usa MyST Markdown, un superset di CommonMark compatibile con Sphinx.
Ogni pagina inizia con frontmatter YAML (titolo, descrizione, argomenti, tag, tipo di contenuto).
Includi l’intestazione della licenza SPDX dopo il frontmatter.

Template del Frontmatter

---
title:
  page: "Titolo della Pagina NemoClaw — Sottotitolo con Contesto"
  nav: "Titolo Breve per la Nav"
description: "Riassunto in una frase della pagina."
keywords: ["parola chiave primaria", "frase chiave secondaria"]
topics: ["generative_ai", "ai_agents"]
tags: ["openclaw", "openshell", "tag", "pertinenti"]
content:
  type: concept | how_to | get_started | tutorial | reference
  difficulty: technical_beginner | technical_intermediate | technical_advanced
  audience: ["developer", "engineer"]
status: published
---

Struttura della Pagina

Titolo H1 corrispondente al valore di title.page.
Un’introduzione di una o due frasi che indica cosa tratta la pagina.
Sezioni organizzate per attività o concetto, usando H2 e H3. Inizia ogni sezione con una frase introduttiva che orienta il lettore.
Una sezione “Passaggi Successivi” in fondo con link alle pagine correlate.

Guida di Stile

Scrivi come se stessi spiegando qualcosa a un collega. Sii diretto, specifico e conciso.

Voce e Tono

Usa la voce attiva. “La CLI crea un gateway” e non “Un gateway viene creato dalla CLI.”
Usa la seconda persona (“tu”) quando ti rivolgi al lettore.
Usa il presente. “Il comando restituisce un errore” e non “Il comando restituirà un errore.”
Esponi i fatti. Non attenuare con “semplicemente,” “basta,” “facilmente,” o “ovviamente.”

Cose da Evitare

Questi pattern sono comuni nei testi generati da LLM e minano la fiducia dei lettori tecnici. Rimuovili durante la revisione.

Pattern	Problema	Soluzione
Grassetto non necessario	”Questo è un passaggio critico” su istruzioni di routine.	Riserva il grassetto per etichette UI, nomi di parametri e avvisi genuini.
Trattini em ovunque	”Il gateway — che gira in Docker — crea le sandbox.”	Usa le virgole o dividi in due frasi. I trattini em vanno bene con moderazione ma non dovrebbero apparire più volte per paragrafo.
Superlativi	”OpenShell offre un’esperienza potente, robusta e fluida.”	Descrivi cosa fa, non quanto è eccezionale.
Parole attenuanti	”Esegui semplicemente il comando” o “Puoi facilmente configurare…”	Elimina l’avverbio. “Esegui il comando.”
Emoji nel testo	”Iniziamo!”	Niente emoji nel testo della documentazione.
Domande retoriche	”Vuoi proteggere i tuoi agenti? Non cercare oltre!”	Esponi lo scopo direttamente.

Regole di Formattazione

Termina ogni frase con un punto.
Una frase per riga nel file sorgente (rende i diff leggibili).
Usa la formattazione code per comandi CLI, percorsi file, flag, nomi di parametri e valori.
Usa blocchi di codice con il linguaggio console per gli esempi CLI. Prefissa i comandi con $:
```
$ nemoclaw onboard
```
Usa le tabelle per confronti strutturati. Mantieni le tabelle semplici (nessuna formattazione annidata).
Usa admonition con blockquote (> **Nota:**, > **Attenzione:**) per le note, non testo in grassetto.
Evita admonition annidate.
Non numerare i titoli delle sezioni. Scrivi “Effettua il Deploy di un Gateway” e non “Sezione 1: Effettua il Deploy di un Gateway” o “Passaggio 3: Verifica.”
Non usare i due punti nei titoli. Scrivi “Effettua il Deploy e Gestisci i Gateway” e non “Gateway: Deploy e Gestione.”
Usa i due punti solo per introdurre un elenco. Non usare i due punti come punteggiatura generica tra le clausole.

Lista dei Termini

Usa questi in modo coerente:

Usa	Non usare
gateway	Gateway (a meno che non inizi una frase)
sandbox	Sandbox (a meno che non inizi una frase)
CLI	cli, Cli
API key	api key, API Key
NVIDIA	Nvidia, nvidia
NemoClaw	nemoclaw (nel testo), Nemoclaw
OpenClaw	openclaw (nel testo), Openclaw
OpenShell	Open Shell, openShell, Openshell, openshell
mTLS	MTLS, mtls
YAML	yaml, Yaml

Inviare Modifiche alla Documentazione

Crea un branch seguendo la convenzione del progetto.
Effettua le modifiche.
Compila in locale con make docs e verifica l’output.
Apri una PR con docs: come tipo di conventional commit.

docs: update quickstart for new onboard wizard

Se la modifica alla documentazione accompagna una modifica al codice, includi entrambe nella stessa PR e usa il tipo di commit della modifica al codice:

feat(cli): add policy-add command

Revisionare le PR della Documentazione

Quando revisioni la documentazione:

Verifica che le regole della guida di stile sopra riportate siano rispettate.
Cerca i pattern generati da LLM (grassetto eccessivo, trattini em, parole di riempimento).
Verifica che gli esempi di codice siano accurati ed eseguibili.
Conferma che i riferimenti incrociati e i link non siano rotti.
Compila in locale per verificare il rendering.