Contribuindo com a Documentação do NemoClaw

Este guia aborda como escrever, editar e revisar a documentação do NemoClaw. Se você alterar código que afeta o comportamento voltado ao usuário, atualize a documentação relevante no mesmo PR.

Use as Habilidades do Agente

Se você usa um agente de codificação com IA (Cursor, Claude Code, Codex, etc.), o repositório inclui habilidades que automatizam o trabalho de documentação. Use-as antes de escrever do zero.

As habilidades ficam em .agents/skills/ e seguem o guia de estilo abaixo automaticamente. Para usar uma, peça ao seu agente para executá-la. Por exemplo, peça para “atualizar a documentação para tudo que foi mesclado desde a v0.2.0”.

Quando Atualizar a Documentação

Atualize a documentação quando sua alteração:

• Adicionar, remover ou renomear um comando ou flag do CLI.
• Alterar o comportamento ou configuração padrão.
• Adicionar uma nova funcionalidade com a qual os usuários interagem.
• Corrigir um bug que a documentação descreve incorretamente.
• Alterar uma API, protocolo ou esquema de política.

Compilando a Documentação Localmente

Verifique se a documentação está compilada corretamente compilando-a e verificando a saída.

Para compilar a documentação, execute:

make docs

Para servir a documentação localmente e recompilar automaticamente nas alterações, execute:

make docs-live

Convenções de Escrita

Formato

• A documentação usa MyST Markdown, um superconjunto do CommonMark compatível com Sphinx.
• Toda página começa com frontmatter YAML (título, descrição, tópicos, tags, tipo de conteúdo).
• Inclua o cabeçalho de licença SPDX após o frontmatter.

Modelo de Frontmatter

---
title:
  page: "Título da Página NemoClaw — Subtítulo com Contexto"
  nav: "Título Curto para Navegação"
description: "Resumo de uma frase da página."
keywords: ["palavra-chave principal", "frase de palavra-chave secundária"]
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
---

Estrutura da Página

1. Título H1 correspondente ao valor de title.page.
2. Uma introdução de uma ou duas frases indicando o que a página aborda.
3. Seções organizadas por tarefa ou conceito, usando H2 e H3. Comece cada seção com uma frase introdutória que oriente o leitor.
4. Uma seção “Próximos Passos” no final com links para páginas relacionadas.

Guia de Estilo

Escreva como se estivesse explicando algo para um colega. Seja direto, específico e conciso.

Voz e Tom

• Use voz ativa. “O CLI cria um gateway”, não “Um gateway é criado pelo CLI.”
• Use segunda pessoa (“você”) ao se dirigir ao leitor.
• Use o tempo presente. “O comando retorna um erro”, não “O comando retornará um erro.”
• Afirme fatos. Não amenize com “simplesmente”, “apenas”, “facilmente” ou “é claro”.

O Que Evitar

Esses padrões são comuns em texto gerado por LLM e corroem a confiança dos leitores técnicos. Remova-os durante a revisão.

Regras de Formatação

• Termine toda frase com ponto final.
• Uma frase por linha no arquivo-fonte (facilita a leitura de diffs).
• Use formatação code para comandos CLI, caminhos de arquivo, flags, nomes de parâmetros e valores.
• Use blocos de código com a linguagem console para exemplos de CLI. Prefixe comandos com $:

  $ nemoclaw onboard

• Use tabelas para comparações estruturadas. Mantenha as tabelas simples (sem formatação aninhada).
• Use admonições com citação (> **Nota:**, > **Aviso:**) para chamadas de atenção, não texto em negrito.
• Evite admonições aninhadas.
• Não numere títulos de seções. Escreva “Implantar um Gateway”, não “Seção 1: Implantar um Gateway” ou “Passo 3: Verificar.”
• Não use dois-pontos em títulos. Escreva “Implantar e Gerenciar Gateways”, não “Gateways: Implantar e Gerenciar.”
• Use dois-pontos apenas para introduzir uma lista. Não use dois-pontos como pontuação de uso geral entre cláusulas.

Lista de Termos

Use estes de forma consistente:

Enviando Alterações na Documentação

1. Crie um branch seguindo a convenção do projeto.
2. Faça suas alterações.
3. Compile localmente com make docs e verifique a saída.
4. Abra um PR com docs: como tipo de commit convencional.

docs: update quickstart for new onboard wizard

Se sua alteração na documentação acompanha uma alteração de código, inclua ambas no mesmo PR e use o tipo de commit da alteração de código:

feat(cli): add policy-add command

Revisando PRs de Documentação

Ao revisar documentação:

• Verifique se as regras do guia de estilo acima são seguidas.
• Fique atento a padrões gerados por LLM (negrito excessivo, travessões, preenchimento).
• Verifique se os exemplos de código são precisos e executáveis.
• Confirme que referências cruzadas e links não estão quebrados.
• Compile localmente para verificar a renderização.