Wiki Style Guide

Wiki style guide

Language: English · 简体中文

This guide defines how the LWC public Wiki is written, localized, reviewed, and maintained. It follows GitHub Wiki conventions and adapts established open-source documentation practices: direct language, task-focused pages, stable navigation, verifiable commands, and synchronized localization.

Canonical language and localization

• English is the canonical technical text and uses U.S. English.
• Every core content page has a complete Simplified Chinese mirror named <Page>-zh-CN.md.
• A Chinese page is a localized technical document, not a sentence-by-sentence machine translation.
• Both versions must communicate the same requirements, boundaries, examples, warnings, and completion criteria.
• Update both pages in the same commit whenever shared meaning changes.

Each page begins with a language switch:

> **Language:** English · [简体中文](Page-zh-CN)

> **语言：** [English](Page) · 简体中文

File naming and navigation

• Use stable English kebab-style page names in Title Case, such as Document-Knowledge-Graph.md.
• Add -zh-CN before .md for the Chinese mirror.
• Keep Home.md, Home-zh-CN.md, _Sidebar.md, and _Footer.md as special GitHub Wiki files.
• The repository is physically flat. _Sidebar.md expresses the conceptual hierarchy.
• Do not publish dead navigation links. Add a page to the sidebar only after both language versions pass review.
• Prefer standard relative Markdown links without the .md suffix.

Page types

Concept page

Use for architecture, terminology, or a capability model:

1. one-sentence definition;
2. problem or motivation;
3. conceptual model;
4. boundaries and non-goals;
5. relationship to other capabilities;
6. next relevant page.

Task page

Use for installation, configuration, recovery, or a workflow:

1. when to use the task;
2. prerequisites and side effects;
3. numbered steps;
4. verification evidence;
5. failure and recovery guidance;
6. next relevant page.

Reference page

Use for commands, fields, limits, or error contracts:

1. exact scope and version boundary;
2. compact tables grouped by purpose;
3. authoritative commands or schema;
4. edge cases and limits;
5. links to task-oriented explanations.

Do not turn every page into an exhaustive reference. A reader should be able to understand the purpose before encountering command details.

English style

• Use present tense, active voice, and direct language.
• Address the reader as “you” when giving a task instruction.
• Keep one main idea per paragraph.
• Prefer concrete verbs: “Run”, “Inspect”, “Require”, “Preserve”, “Verify”.
• Avoid idioms, marketing filler, unexplained jargon, and claims about future behavior.
• Use sentence-style capitalization for headings.
• Format commands, filenames, paths, fields, and literal values as code.
• Introduce an LWC-specific term before using its abbreviation or implementation detail.

Chinese style

• Write natural Simplified Chinese for technical readers; restructure the sentence when English word order would sound mechanical.
• Prefer concise verbs such as“运行”“检查”“保留”“验证”, and omit unnecessary subjects when Chinese context is clear.
• Preserve product and protocol names such as LWC, Agent, MCP, CodeGraph, Source, Page, Work, changeset, and checkpoint when translation would reduce precision.
• Explain an English term in Chinese on first use when necessary; do not repeatedly add parentheses afterward.
• Use Chinese punctuation in prose and ASCII punctuation inside code.
• Avoid literal translations such as“做一个决定”“执行一个检查”when“决定”“检查”is sufficient.
• Do not add stronger claims, extra warnings, or product promises that are absent from the English canonical page.

Commands and examples

• Verify commands against the current CLI with lwc <command> --help or a real isolated run.
• Do not include a shell prompt character in command blocks.
• Separate command output from the command that produced it.
• Use angle brackets for placeholders and explain unusual placeholders.
• Never include real tokens, private paths, cookies, credentials, or maintainer-specific environment assumptions.
• Invoke the globally installed lwc command directly. Do not teach routine LWC_PROJECT_ROOT exports or private binary variables.
• State side effects before commands that install software, change configuration, initialize graphs, restore checkpoints, or write outside the current project.

Technical authority

Use evidence in this order:

1. current checked-out implementation and tests;
2. current lwc --help and isolated command behavior;
3. repository policy and maintained README files;
4. current official documentation for integrated third-party tools;
5. historical design notes, clearly labelled when behavior may have changed.

Do not copy a stale Wiki claim into another page. When documentation and current behavior disagree, correct the documentation from current evidence.

Links and duplication

• Give each concept one primary page and link to it from other pages.
• Keep the Home page short and navigational.
• Put procedures in task pages and exact field lists in reference pages.
• Link to the repository's CHANGELOG, releases, security policy, and contribution files instead of duplicating them in the Wiki.
• Use descriptive link text; avoid bare “here” links.
• Verify every internal link before publication.

Bilingual review checklist

Review each pair as one unit:

• filenames and language switches point to each other;
• heading hierarchy and section coverage match semantically;
• no requirement, warning, limit, example, or verification step is missing;
• the Chinese text reads naturally without following English syntax mechanically;
• terminology is consistent with the approved glossary;
• commands, identifiers, JSON fields, and numeric limits are unchanged where required;
• links target the matching language when a mirror exists;
• neither language introduces unsupported facts;
• commands have been checked against current help or an isolated real run;
• Markdown and internal links pass automated validation.

Approved terminology

English	Simplified Chinese guidance
proactive memory	主动记忆
persistent memory	持久记忆；强调跨会话时可写“长期记忆”
source-grounded	有来源依据；在 provenance 字段语境保留 source-grounded
Source	Source（来源）；命令实体名保留英文
Page	Page（页面）；命令实体名保留英文
provenance	来源证明；字段名保留 provenance
document knowledge graph	文档知识图；面向产品概念时可补充“记忆图网”
CodeGraph	CodeGraph 或代码图网
Word Graph	词图网
strong tag	强标签
Work	Work 任务
changeset	changeset；解释为原子变更草稿
checkpoint	checkpoint；解释为完整恢复点
read-only Viewer	只读 Viewer 或只读可视化界面

Publication gate

A page pair is ready only when:

1. both files are complete;
2. technical claims are supported by current evidence;
3. examples use valid commands and safe placeholders;
4. bilingual review passes every applicable checklist item;
5. internal links resolve;
6. the sidebar contains the pair only after these checks pass.

Return to the Home page.