Współtworzenie dokumentacji NemoClaw

Ten przewodnik opisuje, jak pisać, edytować i recenzować dokumentację NemoClaw. Jeśli zmieniasz kod wpływający na zachowanie widoczne dla użytkownika, zaktualizuj odpowiednią dokumentację w tym samym PR.

Korzystaj z umiejętności agenta

Jeśli używasz agenta kodowania AI (Cursor, Claude Code, Codex itp.), repozytorium zawiera umiejętności automatyzujące pracę nad dokumentacją. Użyj ich, zanim zaczniesz pisać od zera.

Umiejętność	Co robi	Kiedy używać
`update-docs`	Skanuje ostatnie commity w poszukiwaniu zmian widocznych dla użytkownika i tworzy szkice aktualizacji dokumentacji.	Po wdrożeniu funkcji, przed wydaniem lub w celu znalezienia luk w dokumentacji.

Umiejętności znajdują się w .agents/skills/ i automatycznie stosują poniższy przewodnik stylu. Aby użyć jednej z nich, poproś swojego agenta o jej uruchomienie. Na przykład poproś o “uzupełnienie dokumentacji o wszystko, co zostało scalone od v0.2.0”.

Kiedy aktualizować dokumentację

Zaktualizuj dokumentację, gdy Twoja zmiana:

Dodaje, usuwa lub zmienia nazwę polecenia CLI lub flagi.
Zmienia domyślne zachowanie lub konfigurację.
Dodaje nową funkcję, z którą użytkownicy wchodzą w interakcję.
Naprawia błąd, który dokumentacja opisuje niepoprawnie.
Zmienia API, protokół lub schemat polityki.

Lokalne budowanie dokumentacji

Zweryfikuj poprawność budowania dokumentacji, budując ją i sprawdzając wyniki.

Aby zbudować dokumentację, uruchom:

make docs

Aby serwować dokumentację lokalnie i automatycznie przebudowywać przy zmianach, uruchom:

make docs-live

Konwencje pisania

Format

Dokumentacja używa MyST Markdown, nadzbioru CommonMark kompatybilnego ze Sphinx.
Każda strona zaczyna się od frontmatter YAML (tytuł, opis, tematy, tagi, typ treści).
Dołącz nagłówek licencji SPDX po frontmatter.

Szablon frontmatter

---
title:
  page: "NemoClaw Tytuł Strony — Podtytuł z kontekstem"
  nav: "Krótki tytuł nawigacji"
description: "Jednozadaniowe podsumowanie strony."
keywords: ["słowo kluczowe główne", "fraza słowa kluczowego pomocniczego"]
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
---

Struktura strony

Nagłówek H1 odpowiadający wartości title.page.
Jedno- lub dwuzdaniowe wprowadzenie opisujące, co obejmuje strona.
Sekcje uporządkowane według zadań lub koncepcji, z użyciem H2 i H3. Każdą sekcję rozpocznij zdaniem wprowadzającym, które orientuje czytelnika.
Sekcja “Następne kroki” na dole z linkami do powiązanych stron.

Przewodnik stylu

Pisz tak, jakbyś wyjaśniał coś koledze. Bądź bezpośredni, konkretny i zwięzły.

Głos i ton

Używaj strony czynnej. “CLI tworzy bramę”, a nie “Brama jest tworzona przez CLI.”
Używaj drugiej osoby (“ty”) zwracając się do czytelnika.
Używaj czasu teraźniejszego. “Polecenie zwraca błąd”, a nie “Polecenie zwróci błąd.”
Przedstawiaj fakty. Nie osłabiaj przekazu słowami “po prostu”, “łatwo” czy “oczywiście.”

Czego unikać

Te wzorce są częste w tekstach generowanych przez LLM i podważają zaufanie wśród czytelników technicznych. Usuwaj je podczas recenzji.

Wzorzec	Problem	Rozwiązanie
Niepotrzebne pogrubienie	”To jest kluczowy krok” przy rutynowych instrukcjach.	Zarezerwuj pogrubienie dla etykiet UI, nazw parametrów i prawdziwych ostrzeżeń.
Nadmiar myślników	”Brama — która działa w Docker — tworzy sandboxy.”	Użyj przecinków lub podziel na dwa zdania. Myślniki są dopuszczalne oszczędnie, ale nie powinny pojawiać się wielokrotnie w jednym akapicie.
Superlatywy	”OpenShell zapewnia potężne, solidne, bezproblemowe doświadczenie.”	Opisz, co robi, a nie jak jest świetne.
Słowa osłabiające	”Po prostu uruchom polecenie” lub “Możesz łatwo skonfigurować…”	Usuń przysłówek. “Uruchom polecenie.”
Emoji w tekście	”Zaczynajmy!”	Bez emoji w tekście dokumentacji.
Pytania retoryczne	”Chcesz zabezpieczyć swoich agentów? Nie szukaj dalej!”	Opisz cel bezpośrednio.

Zasady formatowania

Każde zdanie kończ kropką.
Jedno zdanie w linii w pliku źródłowym (ułatwia czytanie diff-ów).
Używaj formatowania code dla poleceń CLI, ścieżek plików, flag, nazw parametrów i wartości.
Używaj bloków kodu z językiem console dla przykładów CLI. Poprzedzaj polecenia znakiem $:
```
$ nemoclaw onboard
```
Używaj tabel do porównań strukturalnych. Utrzymuj tabele proste (bez zagnieżdżonego formatowania).
Używaj admonitions w blokach cytatu (> **Uwaga:**, > **Ostrzeżenie:**) dla wyróżnień, nie pogrubionego tekstu.
Unikaj zagnieżdżonych admonitions.
Nie numeruj tytułów sekcji. Pisz “Wdróż bramę”, a nie “Sekcja 1: Wdróż bramę” czy “Krok 3: Zweryfikuj.”
Nie używaj dwukropków w tytułach. Pisz “Wdrażanie i zarządzanie bramami”, a nie “Bramy: wdrażanie i zarządzanie.”
Używaj dwukropków tylko do wprowadzenia listy. Nie używaj dwukropków jako ogólnej interpunkcji między zdaniami.

Lista słów

Używaj ich konsekwentnie:

Używaj	Nie używaj
gateway	Gateway (chyba że na początku zdania)
sandbox	Sandbox (chyba że na początku zdania)
CLI	cli, Cli
API key	api key, API Key
NVIDIA	Nvidia, nvidia
NemoClaw	nemoclaw (w tekście), Nemoclaw
OpenClaw	openclaw (w tekście), Openclaw
OpenShell	Open Shell, openShell, Openshell, openshell
mTLS	MTLS, mtls
YAML	yaml, Yaml

Przesyłanie zmian w dokumentacji

Utwórz gałąź zgodnie z konwencją projektu.
Wprowadź swoje zmiany.
Zbuduj lokalnie za pomocą make docs i zweryfikuj wyniki.
Otwórz PR z docs: jako typem conventional commit.

docs: update quickstart for new onboard wizard

Jeśli zmiana dokumentacji towarzyszy zmianie kodu, umieść obie w tym samym PR i użyj typu commita odpowiadającego zmianie kodu:

feat(cli): add policy-add command

Recenzowanie PR-ów dokumentacji

Podczas recenzowania dokumentacji:

Sprawdź, czy powyższe zasady przewodnika stylu są przestrzegane.
Zwracaj uwagę na wzorce generowane przez LLM (nadmierne pogrubienie, myślniki, wypełniacze).
Zweryfikuj, czy przykłady kodu są dokładne i uruchamialne.
Potwierdź, że odnośniki i linki nie są uszkodzone.
Zbuduj lokalnie, aby sprawdzić renderowanie.