Hai Simplified Technical

Hai Simplified Technical

For Chinese readers, see SKILL.zh_CN.md. The English SKILL.md is the execution source of truth.

Overview

Make a technical document readable in one way only: one word for one concept, one topic in one sentence, a named actor for each action, and a fixed set of words for requirements. The rules come from the nine sections of ASD-STE100 Part 1. The English rules keep the STE grammar rules that matter for software text. The Chinese rules drop the English-only grammar and add the faults of Chinese technical writing: hidden verbs (进行, 加以), long pre-noun modifiers, missing subjects, unclear pronouns.

Both languages share one rule numbering. references/rules-en.md and references/rules-zh.md hold the full rules with reasons, examples and checks.

Scope

Technical documents only: text that a reader uses to understand a system, do an operation or make a technical decision. Design docs, READMEs, API references, runbooks, troubleshooting and migration guides, commit messages, PR descriptions, code comments, error messages and UI help text are in scope.

Not marketing or creative text: marketing copy, brand stories, blog and social posts, launch announcements, speeches, fiction. That text works through rhythm, emotion and rhetoric. These rules make it flat and defeat its purpose. Write it normally and do not apply this skill.

Mixed documents: release notes and announcements often mix promotion and technical content. Apply the rules to the technical parts only (what changed, how to upgrade, what breaks).

If the user explicitly asks for these rules on non-technical text, do it, and say once that the text will lose its persuasive tone.

Language

• Write each part in the rules of its own language. Detect the language from the document, not from the conversation.
• A Chinese document with English terms uses the Chinese rules; 9.1 decides how the terms appear.
• A bilingual document applies each language's rules to its own text.
• A translation is not part of this skill. When the user asks for one, translate first, then apply the rules of the target language.

Workflow

1. Check the scope. Confirm that the text is technical (see Scope).
2. Find the project conventions. Look for a glossary and a style guide (section 10 of the rule files says where). Project conventions win over these rules, for example a quotation style or a fixed translation.
3. Write or rewrite. Follow the summary below. Open the rule file of the language when a rule is unclear or when you need an example.
4. Run the mechanical check. python3 <skill dir>/scripts/check.py <file> (add --lang en or --lang zh to force one language). It lists places to look at, not verdicts: quoted examples, names next to code, and soft rules kept for a reason can stay.
5. Deliver. Follow references/output-template.md.

Rule summary

Obey every hard rule. Obey about 80% of the soft rules, and have a reason for each one you break.

1 Words

• 1.1 hard: One word for one concept. Do not vary words for style.
• 1.2 hard: One meaning for each word.
• 1.3 hard: Use the glossary. Name a new concept before you use it.
• 1.4 hard: No vague words. EN: appropriate, relevant, various, significant, fairly, basically. ZH: 适当、有关的、一定程度上、较为、基本上、若干、显著、大幅、明显. Give a number, a name or a condition.
• 1.5 soft: Verbs that say what happens. EN: handle, process, manage, optimize. ZH: 处理、操作、支持、优化、调整.

2 Noun phrases

• 2.1 soft: At most two modifiers before a noun. ZH: at most two 的.
• 2.2 soft: At most three nouns together.
• 2.3 hard: Modifier markers. EN: hyphenate a compound modifier before a noun. ZH: use 的/地/得 correctly.

3 Verbs

• 3.1 hard: Do not hide the verb in a noun. EN: perform, carry out, conduct, make an adjustment. ZH: 进行、加以、予以、做出、实现了对……的.
• 3.2 soft: Active voice; name the actor. EN: passive. ZH: 被, 由……做.
• 3.3 soft: State facts in the simple tense. EN: no "is sending". ZH: no 正在, no 着 for state.
• 3.4 hard: Fixed requirement words. EN: must / must not / should / should not / can / need not (or the project's RFC 2119 words). ZH: 应 / 不应 / 宜 / 不宜 / 可 / 不必.
• 3.5 soft, EN only: A one-word verb when one exists ("find", not "find out").

4 Sentences

• 4.1 hard: One topic in each sentence.
• 4.2 hard: Name the actor. EN: no empty "It is / There is", no dangling modifiers. ZH: write the subject when it changes.
• 4.3 hard: Each pronoun points to one thing. EN: no bare "this". ZH: 它、这、该、其.
• 4.4 soft: Show the connection: because, so, if, but / 因为、所以、如果、但.
• 4.5 soft: A vertical list for three or more items.
• 4.6 hard, EN only: Do not leave out articles or "that" (no telegraph style).

5 Procedures

• 5.1 hard: Numbered list, one instruction in each step.
• 5.2 hard: Start each step with an imperative verb.
• 5.3 hard: Condition before instruction ("If X, do Y").
• 5.4 soft: Step sentences at most 20 words (EN) or 40 characters (ZH).
• 5.5 soft: Reasons before the list; each result after its step.

6 Descriptive writing

• 6.1 hard: Conclusion first in each paragraph.
• 6.2 soft: One topic in each paragraph, at most six sentences.
• 6.3 soft: Descriptive sentences at most 25 words (EN) or 50 characters (ZH).
• 6.4 hard: Every measured number has its conditions and date.
• 6.5 hard: Keep what is done apart from what is planned.

7 Warnings

• 7.1 hard: A warning comes before the step it applies to.
• 7.2 hard: The instruction first, then the risk.
• 7.3 soft: One risk in each warning.
• 7.4 hard: Two levels. Warning / 警告: data loss, irreversible, wrong without an error, production impact, publishing outside. Caution / 注意: slower, rework, long wait.

8 Punctuation, numbers, length

• 8.1 hard: EN: ASCII punctuation. ZH: full-width punctuation.
• 8.2 hard: One quotation style in each document.
• 8.3 hard: EN: a space between number and unit. ZH: a space between Chinese and Latin letters or digits.
• 8.6 hard: Ranges with "–" (or "to" / "到"), never "~".
• 8.7 hard: Dates that cannot be misread; ISO in tables and parentheses.
• 8.8 hard: Count EN words between spaces; count ZH characters, plus one for each Latin word, number or code span.

9 Writing practices

• 9.1 hard: One form for each term. EN: one spelling and case. ZH: the original or one fixed translation.
• 9.2 hard: Code names in backticks, exactly as in the code.
• 9.3 hard: Official product names; abbreviations defined at first use.
• 9.4 soft: No idioms, filler or marketing words. EN: seamless, leverage, simply, just, easily. ZH: 开箱即用、无缝、一劳永逸、赋能.
• 9.7 soft, EN only: No contractions; no e.g., i.e., etc., via.