Bijdragen aan NemoClaw-documentatie

Deze handleiding beschrijft hoe u documentatie voor NemoClaw schrijft, bewerkt en beoordeelt. Als u code wijzigt die het gebruikersgedrag beïnvloedt, werk dan de relevante documentatie bij in dezelfde PR.

Gebruik de Agent Skills

Als u een AI-coderingsagent gebruikt (Cursor, Claude Code, Codex, etc.), bevat de repository skills die documentatiewerk automatiseren. Gebruik deze voordat u vanaf nul begint te schrijven.

Skill	Wat het doet	Wanneer te gebruiken
`update-docs`	Scant recente commits op gebruikersgerichte wijzigingen en stelt documentatie-updates op.	Na het landen van functies, voor een release, of om documentatielacunes te vinden.

De skills bevinden zich in .agents/skills/ en volgen automatisch de onderstaande stijlgids. Om er een te gebruiken, vraag uw agent om deze uit te voeren. Vraag bijvoorbeeld om “de documentatie bij te werken voor alles dat is samengevoegd sinds v0.2.0”.

Wanneer documentatie bijwerken

Werk de documentatie bij wanneer uw wijziging:

Een CLI-commando of vlag toevoegt, verwijdert of hernoemt.
Standaardgedrag of configuratie wijzigt.
Een nieuwe functie toevoegt waarmee gebruikers interactie hebben.
Een bug repareert die de documentatie onjuist beschrijft.
Een API, protocol of beleidsschema wijzigt.

Documentatie lokaal bouwen

Controleer of de documentatie correct is gebouwd door deze te bouwen en de uitvoer te controleren.

Om de documentatie te bouwen, voer uit:

make docs

Om de documentatie lokaal te serveren en automatisch te herbouwen bij wijzigingen, voer uit:

make docs-live

Schrijfconventies

Formaat

Documentatie gebruikt MyST Markdown, een Sphinx-compatibele superset van CommonMark.
Elke pagina begint met YAML-frontmatter (titel, beschrijving, onderwerpen, tags, inhoudstype).
Voeg de SPDX-licentieheader toe na de frontmatter.

Frontmatter-sjabloon

---
title:
  page: "NemoClaw-paginatitel — Ondertitel met context"
  nav: "Korte navigatietitel"
description: "Samenvatting van de pagina in één zin."
keywords: ["primair trefwoord", "secundaire trefwoordzin"]
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
---

Paginastructuur

H1-kop die overeenkomt met de title.page-waarde.
Een inleiding van één of twee zinnen die beschrijft wat de pagina behandelt.
Secties georganiseerd per taak of concept, met H2 en H3. Begin elke sectie met een inleidende zin die de lezer oriënteert.
Een sectie “Volgende stappen” onderaan met links naar gerelateerde pagina’s.

Stijlgids

Schrijf alsof u iets uitlegt aan een collega. Wees direct, specifiek en beknopt.

Toon en stijl

Gebruik actieve vorm. “De CLI maakt een gateway aan” niet “Een gateway wordt aangemaakt door de CLI.”
Gebruik de tweede persoon (“u”) wanneer u de lezer aanspreekt.
Gebruik tegenwoordige tijd. “Het commando geeft een fout” niet “Het commando zal een fout geven.”
Vermeld feiten. Gebruik geen verzachtende woorden zoals “gewoon,” “eenvoudig,” “makkelijk,” of “natuurlijk.”

Te vermijden patronen

Deze patronen komen veel voor in door LLM gegenereerde tekst en ondermijnen het vertrouwen bij technische lezers. Verwijder ze tijdens de beoordeling.

Patroon	Probleem	Oplossing
Onnodig vet	”Dit is een cruciale stap” bij routinematige instructies.	Reserveer vet voor UI-labels, parameternamen en echte waarschuwingen.
Overal liggende streepjes	”De gateway — die in Docker draait — maakt sandboxes aan.”	Gebruik komma’s of splits in twee zinnen. Liggende streepjes zijn sporadisch prima maar mogen niet meerdere keren per alinea voorkomen.
Superlatieven	”OpenShell biedt een krachtige, robuuste, naadloze ervaring.”	Beschrijf wat het doet, niet hoe geweldig het is.
Verzachtende woorden	”Voer gewoon het commando uit” of “U kunt eenvoudig configureren…”	Schrap het bijwoord. “Voer het commando uit.”
Emoji in tekst	”Laten we beginnen!”	Geen emoji in documentatietekst.
Retorische vragen	”Wilt u uw agents beveiligen? Zoek niet verder!”	Vermeld het doel direct.

Opmaakregels

Eindig elke zin met een punt.
Eén zin per regel in het bronbestand (maakt diffs leesbaar).
Gebruik code-opmaak voor CLI-commando’s, bestandspaden, vlaggen, parameternamen en waarden.
Gebruik codeblokken met de taal console voor CLI-voorbeelden. Zet commando’s vooraf met $:
```
$ nemoclaw onboard
```
Gebruik tabellen voor gestructureerde vergelijkingen. Houd tabellen eenvoudig (geen geneste opmaak).
Gebruik blockquote-admonities (> **Opmerking:**, > **Waarschuwing:**) voor bijzonderheden, niet vette tekst.
Vermijd geneste admonities.
Nummer sectietitels niet. Schrijf “Een gateway deployen” niet “Sectie 1: Een gateway deployen” of “Stap 3: Verifiëren.”
Gebruik geen dubbele punten in titels. Schrijf “Gateways deployen en beheren” niet “Gateways: deployen en beheren.”
Gebruik dubbele punten alleen om een lijst in te leiden. Gebruik geen dubbele punten als algemene leestekens tussen bijzinnen.

Woordenlijst

Gebruik deze consequent:

Gebruik	Gebruik niet
gateway	Gateway (tenzij aan het begin van een zin)
sandbox	Sandbox (tenzij aan het begin van een zin)
CLI	cli, Cli
API key	api key, API Key
NVIDIA	Nvidia, nvidia
NemoClaw	nemoclaw (in tekst), Nemoclaw
OpenClaw	openclaw (in tekst), Openclaw
OpenShell	Open Shell, openShell, Openshell, openshell
mTLS	MTLS, mtls
YAML	yaml, Yaml

Documentatiewijzigingen indienen

Maak een branch aan volgens de projectconventie.
Breng uw wijzigingen aan.
Bouw lokaal met make docs en controleer de uitvoer.
Open een PR met docs: als het conventionele committype.

docs: update quickstart for new onboard wizard

Als uw documentatiewijziging een codewijziging begeleidt, neem dan beide op in dezelfde PR en gebruik het committype van de codewijziging:

feat(cli): add policy-add command

Documentatie-PR’s beoordelen

Bij het beoordelen van documentatie:

Controleer of de bovenstaande stijlgidsregels worden gevolgd.
Let op door LLM gegenereerde patronen (overmatig vet, liggende streepjes, opvulling).
Controleer of codevoorbeelden correct en uitvoerbaar zijn.
Bevestig dat kruisverwijzingen en links niet gebroken zijn.
Bouw lokaal om de weergave te controleren.