Đóng góp cho tài liệu NemoClaw

Hướng dẫn này trình bày cách viết, chỉnh sửa và đánh giá tài liệu cho NemoClaw. Nếu bạn thay đổi mã ảnh hưởng đến hành vi mà người dùng nhìn thấy, hãy cập nhật tài liệu liên quan trong cùng một PR.

Sử dụng các kỹ năng của Agent

Nếu bạn sử dụng agent lập trình AI (Cursor, Claude Code, Codex, v.v.), kho lưu trữ bao gồm các kỹ năng tự động hóa công việc tài liệu. Hãy sử dụng chúng trước khi viết từ đầu.

Kỹ năng	Chức năng	Khi nào sử dụng
`update-docs`	Quét các commit gần đây để tìm thay đổi ảnh hưởng đến người dùng và soạn bản cập nhật tài liệu.	Sau khi tích hợp tính năng, trước khi phát hành, hoặc để tìm lỗ hổng trong tài liệu.

Các kỹ năng nằm trong .agents/skills/ và tự động tuân theo hướng dẫn phong cách bên dưới. Để sử dụng, hãy yêu cầu agent của bạn chạy nó. Ví dụ, yêu cầu “cập nhật tài liệu cho tất cả những gì đã merge kể từ v0.2.0”.

Khi nào cần cập nhật tài liệu

Cập nhật tài liệu khi thay đổi của bạn:

Thêm, xóa hoặc đổi tên một lệnh hoặc cờ CLI.
Thay đổi hành vi mặc định hoặc cấu hình.
Thêm một tính năng mới mà người dùng tương tác.
Sửa lỗi mà tài liệu mô tả không chính xác.
Thay đổi API, giao thức hoặc lược đồ chính sách.

Xây dựng tài liệu cục bộ

Xác minh tài liệu được xây dựng đúng bằng cách biên dịch và kiểm tra kết quả.

Để xây dựng tài liệu, chạy:

make docs

Để phục vụ tài liệu cục bộ và tự động biên dịch lại khi có thay đổi, chạy:

make docs-live

Quy ước viết

Định dạng

Tài liệu sử dụng MyST Markdown, một tập mở rộng tương thích Sphinx của CommonMark.
Mỗi trang bắt đầu bằng YAML frontmatter (title, description, topics, tags, content type).
Bao gồm header giấy phép SPDX sau frontmatter.

Mẫu Frontmatter

---
title:
  page: "NemoClaw Page Title — Subtitle with Context"
  nav: "Short Nav Title"
description: "One-sentence summary of the page."
keywords: ["primary keyword", "secondary keyword phrase"]
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
---

Cấu trúc trang

Tiêu đề H1 khớp với giá trị title.page.
Một hoặc hai câu giới thiệu nêu rõ trang đề cập nội dung gì.
Các phần được tổ chức theo nhiệm vụ hoặc khái niệm, sử dụng H2 và H3. Bắt đầu mỗi phần bằng một câu giới thiệu giúp người đọc định hướng.
Phần “Bước tiếp theo” ở cuối trang với liên kết đến các trang liên quan.

Hướng dẫn phong cách

Viết như thể bạn đang giải thích điều gì đó cho đồng nghiệp. Trực tiếp, cụ thể và ngắn gọn.

Giọng văn và ngữ điệu

Sử dụng thể chủ động. “CLI tạo một gateway” chứ không phải “Một gateway được tạo bởi CLI.”
Sử dụng ngôi thứ hai (“bạn”) khi nói với người đọc.
Sử dụng thì hiện tại. “Lệnh trả về lỗi” chứ không phải “Lệnh sẽ trả về lỗi.”
Phát biểu sự thật. Không dùng từ mập mờ như “đơn giản là,” “chỉ cần,” “dễ dàng,” hoặc “tất nhiên.”

Những điều cần tránh

Các mẫu này thường thấy trong văn bản do LLM tạo ra và làm giảm độ tin cậy với người đọc kỹ thuật. Loại bỏ chúng trong quá trình đánh giá.

Mẫu	Vấn đề	Cách sửa
In đậm không cần thiết	”Đây là bước quan trọng” trên hướng dẫn thông thường.	Chỉ dùng in đậm cho nhãn giao diện, tên tham số và cảnh báo thực sự.
Gạch ngang em ở khắp nơi	”Gateway — chạy trong Docker — tạo sandbox.”	Dùng dấu phẩy hoặc tách thành hai câu. Gạch ngang em thỉnh thoảng thì được nhưng không nên xuất hiện nhiều lần trong một đoạn.
Từ ngữ tối cao	”OpenShell cung cấp trải nghiệm mạnh mẽ, vững chắc, liền mạch.”	Nói nó làm gì, không phải nó tuyệt vời thế nào.
Từ mập mờ	”Chỉ cần chạy lệnh” hoặc “Bạn có thể dễ dàng cấu hình…”	Bỏ trạng từ. “Chạy lệnh.”
Emoji trong văn xuôi	”Hãy bắt đầu nào!”	Không dùng emoji trong văn xuôi tài liệu.
Câu hỏi tu từ	”Muốn bảo mật tác nhân của bạn? Không cần tìm đâu xa!”	Nêu mục đích trực tiếp.

Quy tắc định dạng

Kết thúc mỗi câu bằng dấu chấm.
Mỗi câu một dòng trong tệp nguồn (giúp diff dễ đọc).
Sử dụng định dạng code cho lệnh CLI, đường dẫn tệp, cờ, tên tham số và giá trị.
Sử dụng khối mã với ngôn ngữ console cho ví dụ CLI. Thêm tiền tố $ trước lệnh:
```
$ nemoclaw onboard
```
Sử dụng bảng cho so sánh có cấu trúc. Giữ bảng đơn giản (không lồng định dạng).
Sử dụng chú thích blockquote (> **Lưu ý:**, > **Cảnh báo:**) cho lời nhắc, không dùng văn bản in đậm.
Tránh chú thích lồng nhau.
Không đánh số tiêu đề phần. Viết “Triển khai Gateway” chứ không phải “Phần 1: Triển khai Gateway” hoặc “Bước 3: Xác minh.”
Không dùng dấu hai chấm trong tiêu đề. Viết “Triển khai và quản lý Gateway” chứ không phải “Gateway: Triển khai và quản lý.”
Chỉ dùng dấu hai chấm để giới thiệu danh sách. Không dùng dấu hai chấm làm dấu chấm câu chung giữa các mệnh đề.

Danh sách từ

Sử dụng nhất quán:

Dùng	Không dùng
gateway	Gateway (trừ khi đầu câu)
sandbox	Sandbox (trừ khi đầu câu)
CLI	cli, Cli
API key	api key, API Key
NVIDIA	Nvidia, nvidia
NemoClaw	nemoclaw (trong văn xuôi), Nemoclaw
OpenClaw	openclaw (trong văn xuôi), Openclaw
OpenShell	Open Shell, openShell, Openshell, openshell
mTLS	MTLS, mtls
YAML	yaml, Yaml

Gửi thay đổi tài liệu

Tạo nhánh theo quy ước của dự án.
Thực hiện thay đổi.
Biên dịch cục bộ với make docs và xác minh kết quả.
Mở PR với docs: là kiểu conventional commit.

docs: update quickstart for new onboard wizard

Nếu thay đổi tài liệu đi kèm thay đổi mã, hãy bao gồm cả hai trong cùng một PR và sử dụng kiểu commit của thay đổi mã:

feat(cli): add policy-add command

Đánh giá PR tài liệu

Khi đánh giá tài liệu:

Kiểm tra rằng các quy tắc hướng dẫn phong cách ở trên được tuân thủ.
Chú ý các mẫu do LLM tạo ra (in đậm quá mức, gạch ngang em, nội dung thừa).
Xác minh các ví dụ mã chính xác và có thể chạy được.
Xác nhận tham chiếu chéo và liên kết không bị hỏng.
Biên dịch cục bộ để kiểm tra hiển thị.