105 lines
4.0 KiB
Markdown
105 lines
4.0 KiB
Markdown
---
|
||
description: Create or update repository documentation from current code changes
|
||
argument-hint: Optional: topic to document, or leave empty to infer from git diff
|
||
allowed-tools: ["Read", "Edit", "Write", "Bash", "Glob", "Grep"]
|
||
---
|
||
|
||
# /docs — Documentation Workflow
|
||
|
||
## Goal
|
||
|
||
Create or update documentation that explains why a change exists, how it behaves, and what maintainers need to know. Keep this command generic. Repository-specific coverage rules live in the repository and must be loaded separately.
|
||
|
||
## Repository Rules
|
||
|
||
Before deciding scope, check whether the repository has a documentation rules file:
|
||
|
||
```bash
|
||
test -f docs/documentation-coverage-rules.md && sed -n '1,240p' docs/documentation-coverage-rules.md
|
||
```
|
||
|
||
If it exists, apply it as the project-specific coverage checklist. If it does not exist, continue with the generic workflow below.
|
||
|
||
## Workflow
|
||
|
||
### Step 1 — Understand The Change
|
||
|
||
```bash
|
||
git diff HEAD --stat
|
||
git diff HEAD --name-only
|
||
git log --oneline -10
|
||
rg --files docs
|
||
```
|
||
|
||
If `$ARGUMENTS` specifies a topic, focus on that topic. Otherwise infer the documentation topic from the changed files. Do not read the full repository diff by default; inspect focused files only:
|
||
|
||
```bash
|
||
git diff HEAD -- <path>
|
||
rg -n "class |def |function |export |router|@router|interface |type " <path>
|
||
```
|
||
|
||
### Step 2 — Decide Scope
|
||
|
||
- Prefer updating an existing relevant document over creating a duplicate.
|
||
- Use one document for one coherent topic.
|
||
- Split documents only when the change crosses meaningful domains.
|
||
- Keep filenames lowercase and hyphenated.
|
||
- Apply the repository-specific rules file before writing.
|
||
|
||
#### Document Audience Routing (Planet)
|
||
|
||
In this repository, classify the action's performer before picking a target file:
|
||
|
||
- Browser/UI end user → `docs/technical/{zh,en}/manual.md` or `quickstart.md`.
|
||
- Shell / Docker / log paths / `planet.sh` / SMTP fallbacks / port forwarding → `docs/technical/{zh,en}/ops-runbook.md` (or an existing `ops-*.md`).
|
||
- Second-party developers → existing `*-context.md` / `backend-*.md` / `earth-*.md` files.
|
||
|
||
Never put shell commands, log paths, or Docker operations into `manual.md` / `quickstart.md`. Never put UI button labels or screenshots into `ops-*.md`. When the same action has both a UI and a CLI path, write each in its own home and cross-link them with one sentence.
|
||
|
||
For ambiguous or large documentation changes, briefly state the intended doc plan before editing. For clear small changes, proceed directly.
|
||
|
||
### Step 3 — Write
|
||
|
||
Explain:
|
||
|
||
- Background/problem: what was wrong or missing before.
|
||
- Core design decisions and rationale.
|
||
- Operational or user-facing impact.
|
||
- Relevant code paths, only when useful for future maintainers.
|
||
|
||
Style:
|
||
|
||
- Follow the repository’s existing language and heading conventions.
|
||
- Use fenced code blocks with language tags.
|
||
- Prefer tables for comparisons or parameter lists.
|
||
- Keep snippets concise and relevant.
|
||
- For UI labels, chart labels, feature names, datasource names, and other terms that may become mixed Chinese/English copy, check `docs/technical/{zh,en}/naming-glossary.md` and use the documented display name. If a confusing term is missing, update the glossary in both languages as part of the docs change.
|
||
|
||
### Step 4 — Verify
|
||
|
||
- Read the completed docs once for clarity and stale statements.
|
||
- Verify referenced paths exist with `test -e` or `rg --files`.
|
||
- Run applicable checks from `docs/documentation-coverage-rules.md`.
|
||
- Check Markdown links use readable user-facing titles unless repository rules allow otherwise.
|
||
|
||
### Step 5 — Report
|
||
|
||
Summarize changed docs and verification:
|
||
|
||
```md
|
||
Updated:
|
||
- path/to/doc.md — what changed
|
||
|
||
Verified:
|
||
- checks that passed
|
||
- checks that could not be run, if any
|
||
```
|
||
|
||
## Hard Constraints
|
||
|
||
- Do not leave placeholder docs.
|
||
- Do not duplicate bilingual files byte-for-byte.
|
||
- Do not reference PR numbers, issue numbers, or the current conversation unless explicitly requested.
|
||
- Do not write changelog-style lists without the reasoning and tradeoffs behind the change.
|
||
- Keep docs maintainable and concise.
|