Add an answer to doc/faq/ and its Chinese counterpart under i18n/zh/faq/.
Invocation: /lc-faq-add <topic or question> — e.g.
/lc-faq-add kafka rebalancing, /lc-faq-add java virtual threads.
Why the translation is part of the job
doc/faq/ is 49 documents across 12 sub-trees and it is 100% translated — 902 of 902
sections. So a new English section does not leave the tree "mostly translated": it leaves
a hole that nothing reports until someone next runs node script/zh.js status faq, and the
page renders a Chinese document with an English gap in the middle of it.
That is why this skill writes both halves in one pass. It is also the difference between
this skill and markdown-doc-writer, which knows neither the tree nor the overlay.
Prime directives
- The Scope line picks the file, not the topic name. Every FAQ opens with one, and it
exists to stop two files growing into the same document. Read the candidates' Scope lines
before choosing — "connection pooling" could plausibly land in
db/,backend/orjava/, and only the Scope lines say which owns it. - File it under the section it belongs to. The FAQs are numbered documents
(
## 1) The Four Pillars of OOP→### 1-1) Encapsulation). A new answer goes under the section that owns the concept, never appended to the end as a loose question. - The Chinese section ships in the same change (see above).
- Every fence is tagged.
```java,```python,```sql,```bash, or```textfor ASCII diagrams and program output. Never a bare```. - Answer the question that gets asked. These are interview notes: the answer leads with the thing you would say out loud, then the mechanism, then the code if code helps. A tutorial that builds up to the answer is the wrong shape.
Where a file lives, and what that decides
The directory is the index category — build-site.js maps the top-level sub-directory:
| Directory | Card category |
|---|---|
doc/faq/java/ |
Java |
doc/faq/backend/ |
Backend |
doc/faq/db/ |
Database |
doc/faq/redis/, kafka/, flink/, sql/ |
Redis, Kafka, Flink, SQL |
doc/faq/spark/ |
Spark & Hadoop |
doc/faq/stream/ |
Streaming |
a file at doc/faq/ root |
General |
An unmapped sub-directory becomes its own capitalised category rather than failing — so a new directory is a decision about the index, and worth naming in the report.
The page name folds the sub-directory in: doc/faq/java/faq_OOP.md → faqs/java_faq_OOP.html.
The card title comes from the H1, and the card description is summarised from the lead
paragraph — so both are worth writing as something a reader would recognise.
The steps
1. Find the file whose Scope line owns it
ls doc/faq/ doc/faq/*/
grep -n "Scope" doc/faq/*/*.md doc/faq/*.md | grep -i "<topic keyword>"
Read the Scope lines of every plausible candidate, not just the one whose filename matches. If the best file is not the obvious one, say so in the report and explain which Scope line decided it.
A new FAQ file is right when no existing Scope line claims the area and the topic is worth more than a section. It needs its own H1 and Scope block:
# gRPC FAQ
> **Scope** — <what this file owns, and what it deliberately does not>.
> **See also**: [`./faq_API_design.md`](./faq_API_design.md) — <why you'd go there>.
---
## 1) <First section>
Add the See also line to the neighbouring file too, so the pair points both ways.
2. Read a neighbour, then place the section
sed -n '1,60p' doc/faq/<dir>/<file>.md
grep -n '^## \|^### ' doc/faq/<dir>/<file>.md
The heading numbering is positional (## 3) → ### 3-2)). Inserting a section in the
middle means renumbering the ones after it — which moves their anchors, so every link
aimed at them has to move in the same change. Prefer appending within the owning section,
and when a renumber is genuinely right, do the link sweep:
grep -rn "#<old-anchor>" doc/ i18n/ site/pages/
3. Write the answer
- lead with the answer, then the mechanism, then code (directive 5);
- bold the key terms the way the neighbours do —
**Pattern**,**Key Idea**; - a table when the answer is a comparison; that is what most of these questions are;
- every fence tagged (directive 4);
- headings never skip a level (
h2→h3, neverh2→h4).
4. Write the Chinese section in the same pass
node script/zh.js sync faq/<dir>/<file>
node script/zh.js todo faq/<dir>/<file> # the new section, with its key
Write it into i18n/zh/faq/<dir>/<file>.md under the key todo printed, keeping every
<!--CODE--> marker in order — compose throws otherwise. Structure and heading order
come from the English document; translate the heading text only. Links keep their English
anchor targets. API, class and command names stay in English.
If the English FAQ has a Scope line, translate it as > **範圍** — … — extractScope
reads both spellings, so the translated line becomes the Chinese card description. Never drop
it: on a file that has one, the Scope line is what defines ownership. For the 32 FAQs with no
Scope line the card falls back to the composed Chinese lead paragraph, so translating that
lead paragraph is what moves the card.
The full rules, and the campaign workflow for a backlog, are
/lc-zh-translate's.
node script/zh.js sync faq/<dir>/<file>
node script/zh.js status --write # regenerates doc/faq-zh-progress.md
doc/faq-zh-progress.md is generated — never hand-edit it.
5. Gate
SKIP_FONTS=1 bash site/build.sh
node site/e2e-check.js _site
npm test --prefix site
e2e-check.js is where a dangling #fragment from a renumbered heading, an untagged fence
that rendered wrong, a broken relative link or a missing page description surfaces. Then
open both faqs/<name>.html and faqs/<name>.zh.html — the navbar's Chinese / EN button swaps
between them.
6. Report
Close with: the file and section, which Scope line decided it, whether anything was
renumbered and what links moved with it, the zh key written, the new
status faq coverage line, and anything left deliberately in English.
Do not
- ❌ pick the file by topic name instead of by Scope line (directive 1)
- ❌ append a loose question to the end of a file instead of filing it under its section
- ❌ ship the English section without its Chinese counterpart (directive 3)
- ❌ leave a fence untagged (directive 4)
- ❌ renumber headings without sweeping the links that pointed at them
- ❌ drop, add or reorder a
<!--CODE-->marker in the translation - ❌ put
category,tierorkindin a translation — FAQs do not carry them at all - ❌ hand-edit
doc/faq-zh-progress.md - ❌ start a new FAQ file when an existing Scope line already claims the area
- ❌ commit or push unless asked
Worked example
/lc-faq-add kafka rebalancing:
| Step | What it produced |
|---|---|
| 1 | three candidates; doc/faq/kafka/faq_kafka.md's Scope line owns consumer-group behaviour, the Streaming one's owns processing semantics — so the Kafka file, named in the report |
| 2 | filed under ## 4) Consumer Groups as ### 4-3) Rebalancing, appended within the section so nothing renumbered and no anchor moved |
| 3 | answer leads with "a rebalance stops the whole group", then the trigger list, then a ```text timeline and a ```bash of kafka-consumer-groups.sh |
| 4 | todo faq/kafka/faq_kafka → one key; translated with both <!--CODE--> markers in place; kafka-consumer-groups.sh and max.poll.interval.ms left in English |
| 5 | build clean, e2e 80/80, status faq back to 903/903 |
| 6 | flagged: doc/faq/stream/faq_stream.md gained a See also line pointing here, since its Scope line touches the same area |