cn-writing Chinese Technical Writing Guidelines

Applies to Chinese technical articles, personal notes, requirements documentation, and changelogs. The goal is accurate information and concise prose that is easy to read and review.

Read this document before writing; when finished, verify each item (see the “Review Checklist”).

1. Title Guidelines

Titles convey information, not advertising: State the topic directly (“Add an R2 Content API to an Astro Static Site”), rather than using an empty shell title such as “My Blog Transformation Journey”
No clickbait: Reject exaggerated phrases such as “Everything You Need to Know in One Article,” “Must Read,” “Shocking,” or “Solve Everything Efficiently”
No ambiguity: Do not use vague titles such as “Some Thoughts on X” or “A Casual Chat About X” that say almost nothing
Length: Blog titles should contain 10–25 Chinese characters. Name technical documents according to search and identification needs; a fixed character count is not required.
Dates and numbering: Leave blog dates to publishing metadata. Keep requirements numbers, versions, or dates when they help distinguish the document.
Act as a memory index: The title should help you recall what the article covered in the future. Before opening it, readers—including your future self—should be able to judge whether it is worth reading

2. Hard Constraints for Prose

After drafting each piece of content, check every item below. It is acceptable only when all checks pass:

Concise: Do not use a paragraph when one sentence is enough. Each paragraph should carry only one core point
Clear: Explain a technical concept in one sentence when it first appears; do not assume the reader already knows it. Break complex processes into ordered lists instead of compressing them into paragraphs
No filler: Remove clichés, pleasantries, preambles, and repetitive summaries. Start directly with the content and do not end with an empty recap
Smooth: Arrange information according to the reader’s needs and connect paragraphs naturally. Do not force every text into a “what, why, how” sequence
Precise terminology: Use accurate terms consistently. Rendering and drawing, and building and compiling, have different meanings; choose the term based on the actual behavior
Readability: Keep each paragraph focused on one point and divide long passages by semantic boundaries; do not judge paragraph length by the number of line breaks in the Markdown source. Use ordered lists for key procedural steps, code blocks for configuration or code, and bold key conclusions where appropriate

3. Avoid Vague or Generic Expressions

Delete the following expressions when they merely fill space. Do not apply mechanical keyword bans to necessary factual comparisons, quotations, or counterexamples.

Universal openings: “In today’s world,” “With the development of…,” “In recent years,” “As is widely known,” “With the spread of the internet”
AI filler phrases: “It is worth mentioning,” “It is worth noting,” “It should be noted,” “Actually,” “In fact,” “It is obvious,” “It is not difficult to see,” “To sum up,” “In conclusion”
Mechanical transitions: Empty transitions such as “First… Second… Finally…” or “On the one hand… on the other hand…” should only be used when the content has a genuine parallel relationship
Rhetorical-question transitions: “Do you know?” “Why does this happen?” “The answer is simple:”
Meta-narration: “This article will introduce…,” “Next, let’s take a look…,” “Let’s get started…” Do not preview what the text is about to say; state it directly
Nominalized verbs: Prefer direct verbs over nominalized constructions: 「进行了优化」→「优化了」 (conducted an optimization → optimized); 「做出改变」→「改了」 (made a change → changed); 「加以说明」→「说明」 (provided an explanation → explained)

4. Structural Constraints

Short essays and notes: Use 1–2 paragraphs, without subsections, and state the matter directly
Articles: Keep each section focused on one subtopic. Make h2 headings informative in themselves rather than using structural labels such as “Foreword,” “Body,” or “Conclusion”
Paragraphs and lists: Use a paragraph for the introduction, a same-level list for parallel items, and child lists for subordinate details. Do not turn everything into a list merely for visual consistency; structure the hierarchy according to each item’s actual scope
Ending: Do not write an empty summary. If the text needs a closing, end with a new judgment or conclusion rather than repeating the preceding content
Separate opinions from facts: State facts directly and make it clear when something is an opinion; do not present opinions as facts
State certainty when certainty exists: Do not weaken something you know with “perhaps,” “possibly,” or “probably.” Do not fabricate data, version numbers, or dates
State each point once: Do not repeat the same point in the title, body, and image caption
Tone: A personal tone is acceptable but should remain restrained. Do not sound overly familiar, add emoji, or use internet slang. State opinions directly rather than beginning with “In my opinion”

List Use

Choose the list type according to the relationship between items. Do not number items merely to create visual consistency or add bulk.

Ordered lists: Use them for procedural steps, explicit priorities, or rankings, especially when changing the order changes the meaning
Unordered lists: Use them for parallel requirements, categories, conditional branches, or subordinate details whose reading order does not affect the meaning
Checklists: Use them for items that must be checked and completed individually, not for general explanations
Single point: When a point can be summarized, write “Summary: specific explanation.” Do not force a label onto an ordinary short sentence
Multiple details
- Write only “Summary” for the parent item and place all specific requirements in child lists
- Do not write one requirement under the parent and then use child items to add other parallel requirements
Hierarchy and indentation
- Keep independent requirements at the same level and indent subordinate requirements. Choose ordered or unordered child lists according to their own relationships
- Two levels are usually sufficient. Avoid placing global requirements under local conditions

5. Numbers, Terminology, and Punctuation

Numbers and Terminology

Keep identifiers verbatim: Never translate version numbers, commands, package names, file names, or function names (write
```
astro check
```
, not 「星体检查」)
Keep technical units in their original form: Retain units such as MB, ms, and Hz. Use Chinese measure words for Chinese quantities (一个、两个)
Use Arabic numerals for parameters: Write 512MB, 1–2 minutes, and Step 3; do not write “five hundred and twelve MB”
Chinese-English mixed text: Put one space between Chinese and English text. Do not force spaces around commands or code identifiers; use Markdown inline code instead
Preserve capitalization: Do not change the capitalization of code identifiers in the body text

Punctuation Rules

Chinese prose uses Chinese punctuation, while parentheses use half-width

()

. Keep symbols inside code, paths, and commands unchanged.

Sentence punctuation (，。、：；？！): Use full-width forms throughout Chinese prose. The half-width comma
```
,
```
appears only in code
Enumeration comma: Use the Chinese enumeration comma
```
、
```
for Chinese lists, not a half-width comma:
```
SystemMaxUse=50M
```
、
```
SystemKeepFree=256M
```
Half-width parentheses are allowed: Use half-width parentheses
```
()
```
consistently in Chinese sentences; they are more suitable for code parameters. Do not mix full-width and half-width forms
Quotation marks: Use 「」 for Chinese quotations. Do not wrap code in quotation marks; use backticks instead. Never write
```
"caddy reload"
```
with double quotation marks
Keep identifiers unchanged: Do not modify symbols inside identifiers, including
```
=
```
,
```
/
```
,
```
.
```
,
```
-
```
, and
```
_
```
Sentences consisting entirely of code or commands: Keep them unchanged and do not apply full-width punctuation rules, especially inside code blocks
Markdown syntax is unaffected: Keep tables
```
|
```
, frontmatter YAML, and code block contents unchanged

Examples:

❌ As written	✅ Standardized
新增 2G swapfile(swappiness=30),写入 fstab	新增 2G swapfile(swappiness=30)，写入 fstab
设 SystemMaxUse=50M,SystemKeepFree=256M	设 `SystemMaxUse=50M` 、 `SystemKeepFree=256M`
journald 没设上限,悄悄占掉 1.1GB。	journald 没设上限，悄悄占掉 1.1GB。
用 "caddy reload" 热加载	用 `caddy reload` 热加载

6. Code and Examples

Mark code block languages: Use markers such as
```
```typescript
```
; use single backticks for inline code
Include only the relevant parts: Omit scaffolding and unrelated context. For complete files, use the file path plus key points, or provide a link
Use real example output: Do not fabricate terminal output. Clearly label illustrative output as “Illustrative”
Explain code as needed: Describe its purpose and result when necessary. If the context is already clear, do not force an explanation before and after the code

7. Line Breaks in Markdown Source

Source line breaks support readability in the editor and in Git diffs; paragraph length supports readability after rendering. Review them separately.

Semantic line breaks
- Prefer breaking lines after periods, semicolons, or natural clause boundaries. Do not pull the next sentence onto the current line merely to fit a target line width
- Use approximately 40–60 Chinese characters per line as a reference, but do not count mechanically in mixed-language text
Rendered line breaks: Use ordinary line breaks within the same paragraph. Do not add trailing double spaces or
```
<br>
```
solely to control source line width
Syntactic integrity: Do not split words, inline code, or links, and maintain the correct indentation for continued list items. Do not force line breaks in headings, tables, code blocks, long links, or YAML frontmatter
Editing scope: Follow the repository’s existing Markdown formatting configuration and do not change that configuration merely to control line width. Reformat only the paragraphs involved in the current task; treat a full-document reflow as a separate formatting task

8. Review Checklist

Read the entire text once before submission and check each item:

All six hard constraints pass (concise, clear, no filler, smooth, precise terminology, readable)
Vague filler has been removed, while necessary factual comparisons, quotations, and counterexamples have been retained
The title follows “1. Title Guidelines”
Identifiers, units, and numbers follow “5. Numbers, Terminology, and Punctuation”
Code blocks have language markers and example output is accurate
Technical descriptions match actual code behavior and contain no fabricated details
Source lines break at semantic boundaries, and unrelated content has not been reflowed
List types match sequential or parallel relationships, with clear placement of parent summaries and child details
Full-text review: subject-verb collocation, word order, repetition, and logical jumps

cn-writing

NPX Install

Tags

SKILL.md Content (Chinese)