Contribuir a la Documentación de NemoClaw

Esta guía cubre cómo escribir, editar y revisar la documentación de NemoClaw. Si modifica código que afecta el comportamiento visible para el usuario, actualice la documentación correspondiente en el mismo PR.

Usar las Habilidades del Agente

Si utiliza un agente de codificación con IA (Cursor, Claude Code, Codex, etc.), el repositorio incluye habilidades que automatizan el trabajo de documentación. Úselas antes de escribir desde cero.

Las habilidades se encuentran en .agents/skills/ y siguen la guía de estilo que se describe a continuación de forma automática. Para usar una, pídale a su agente que la ejecute. Por ejemplo, pídale que “ponga al día la documentación para todo lo fusionado desde v0.2.0”.

Cuándo Actualizar la Documentación

Actualice la documentación cuando su cambio:

• Agregue, elimine o renombre un comando o flag del CLI.
• Cambie el comportamiento o la configuración predeterminada.
• Agregue una nueva funcionalidad con la que los usuarios interactúen.
• Corrija un error que la documentación describe incorrectamente.
• Cambie un esquema de API, protocolo o política.

Compilar la Documentación Localmente

Verifique que la documentación se compile correctamente compilándola y revisando el resultado.

Para compilar la documentación, ejecute:

make docs

Para servir la documentación localmente y recompilar automáticamente ante cambios, ejecute:

make docs-live

Convenciones de Escritura

Formato

• La documentación usa MyST Markdown, un superconjunto de CommonMark compatible con Sphinx.
• Cada página comienza con frontmatter YAML (título, descripción, temas, etiquetas, tipo de contenido).
• Incluya el encabezado de licencia SPDX después del frontmatter.

Plantilla de Frontmatter

---
title:
  page: "Título de la Página de NemoClaw — Subtítulo con Contexto"
  nav: "Título Corto de Navegación"
description: "Resumen de la página en una oración."
keywords: ["palabra clave principal", "frase de palabra clave secundaria"]
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
---

Estructura de la Página

1. Encabezado H1 que coincida con el valor de title.page.
2. Una introducción de una o dos oraciones indicando qué cubre la página.
3. Secciones organizadas por tarea o concepto, usando H2 y H3. Comience cada sección con una oración introductoria que oriente al lector.
4. Una sección de “Siguientes Pasos” al final con enlaces a páginas relacionadas.

Guía de Estilo

Escriba como si estuviera explicando algo a un colega. Sea directo, específico y conciso.

Voz y Tono

• Use voz activa. “El CLI crea un gateway” en lugar de “Un gateway es creado por el CLI.”
• Use la segunda persona (“usted”) al dirigirse al lector.
• Use el tiempo presente. “El comando devuelve un error” en lugar de “El comando devolverá un error.”
• Exponga hechos. No use expresiones atenuantes como “simplemente,” “solo,” “fácilmente” o “por supuesto.”

Cosas que Evitar

Estos patrones son comunes en texto generado por LLM y erosionan la confianza de los lectores técnicos. Elimínelos durante la revisión.

Reglas de Formato

• Termine cada oración con un punto.
• Una oración por línea en el archivo fuente (facilita la lectura de los diffs).
• Use formato de código para comandos del CLI, rutas de archivos, flags, nombres de parámetros y valores.
• Use bloques de código con el lenguaje console para ejemplos del CLI. Prefije los comandos con $:

  $ nemoclaw onboard

• Use tablas para comparaciones estructuradas. Mantenga las tablas simples (sin formato anidado).
• Use advertencias con citas (> **Nota:**, > **Advertencia:**) para llamadas de atención, no texto en negrita.
• Evite las advertencias anidadas.
• No numere los títulos de las secciones. Escriba “Desplegar un Gateway” en lugar de “Sección 1: Desplegar un Gateway” o “Paso 3: Verificar.”
• No use dos puntos en los títulos. Escriba “Desplegar y Administrar Gateways” en lugar de “Gateways: Desplegar y Administrar.”
• Use dos puntos solo para introducir una lista. No use dos puntos como puntuación de propósito general entre cláusulas.

Lista de Palabras

Use estas de forma consistente:

Enviar Cambios de Documentación

1. Cree una rama siguiendo la convención del proyecto.
2. Realice sus cambios.
3. Compile localmente con make docs y verifique el resultado.
4. Abra un PR con docs: como tipo de commit convencional.

docs: update quickstart for new onboard wizard

Si su cambio de documentación acompaña un cambio de código, incluya ambos en el mismo PR y use el tipo de commit del cambio de código:

feat(cli): add policy-add command

Revisar PRs de Documentación

Al revisar documentación:

• Verifique que se sigan las reglas de la guía de estilo anteriores.
• Busque patrones generados por LLM (negrita excesiva, guiones largos, relleno).
• Verifique que los ejemplos de código sean precisos y ejecutables.
• Confirme que las referencias cruzadas y los enlaces no estén rotos.
• Compile localmente para verificar la renderización.