gracker-writing

Technical Article Writing

A writing skill for technical practitioners, especially suitable for content on Android, performance optimization, engineering tools, and system mechanisms. Writing positioning: engineer's perspective, technically precise, clearly structured, unambiguous judgments, strong traces of real practice, not showing off and not putting on airs. Long-form articles are written according to this document; for X/Twitter, social summaries, and publishable drafts for scheduled tasks, first build the structure according to the corresponding platform skill, then review according to references/social-output-gate.md .

The core of a technical article is three things:

1. Accurate: terminology, versions, paths, code, and data all line up.
2. Useful: after reading, readers know how to observe, how to judge, and how to get started.
3. Easy to read: not cramming in information, but explaining complex problems smoothly.

It is not news aggregation, not emotional venting, not AI-style tidy nonsense, and not writing fancy tricks just to look good.

Human-feel baseline

Writing, rewriting, and pre-publication quality checks must all read references/human-feel.md. These rules absorb the essence of human-writing , but are re-expressed according to Gracker's technical writing system: concrete facts first, simple verbs, less elevation, no forced triads, stable reuse of terminology, clear sources of opinions, restrained bolding, no affectation.

Human-feel does not rely on colloquial performance; it relies on three things:

• Concrete: you can see scenarios, tools, versions, traces, code paths, failure branches, or reader feedback.
• Trade-offs: know why the author judges this way, and also know under what conditions this judgment holds.
• No pretending: do not write ordinary facts as trends of the times, do not write material organization as profound insight, and do not mistake formatting emphasis for content emphasis.

Mannered prose：Delete all mannered prose. When a literal statement is available, use it directly; do not replace accurate meaning with metaphor, pretty words, or writerly posturing. Remove all mannered prose. When a literal statement is available, use it instead of metaphor, flourish, or language that performs the writer rather than conveying the meaning.

If a passage has no concrete object, concrete action, or concrete evidence, even if the tone is smooth, it is still treated as failing at the author layer — what is missing is material, not "not human enough."

Removing AI flavor is divided into two layers; do not mix them. The corpus layer reads references/less-ai-tone.md: fine polishing changes only the 11 items with trigger markers, adding or removing no information. The author layer still reads this section and human-feel.md. Fine polishing is prohibited from using "sounds human-written" to add colloquialisms, adjust sentence length, delete questions, delete metaphors, or treat passive sentences as translationese; those items cannot be supported by the corpus.

Social drafts and news drafts add one more item, the out-loud test: after writing, read every sentence out loud. If it sounds like writing a lead for materials, like commenting on how an official website lays out its pages, or like analyzing how a review organization structures an article, and a normal person would not say this to a colleague, rewrite the whole sentence. Use products, models, and numbers as subjects, not "the official website makes the visuals/selling points/narrative..." Comparative sentences must include two concrete numbers; empty comparisons like "jumps more" and "large increase" are prohibited. For details, see references/human-feel.md under "Thinking Path".

Social output gatekeeping

Publishable drafts for X/Twitter, threads, Xiaohongshu, social summaries, and scheduled tasks posted to Telegram cannot just pass a wordlist. Before delivery, you must read references/social-output-gate.md。

The most common failure in this kind of draft is not banned words, but turning a changelog into a "clean long post": negative opening, feature points one two three, elevated packaging, slogan ending. If it hits any 2 of the "failure means rewrite" items in that file, rewrite the whole piece; do not do surface-level replacement.

When DeepResearch, research results, or review summaries are to be published as social long-form content (Zhihu/WeChat official account/forwardable long posts), first read references/research-social-longform.md. Advance with "surprise → comparison numbers → accompanying image → real question"; do not use the section names of a research report as subheadings. Borrow only the structure, not the sample's verbal tics.

Platform structure follows the corresponding skill (such as x-tweet-writer). Writing style, AI flavor, elevation, and ending follow this skill. The social body must not contain internal processes, paths, skill names, or QA reports. A publishable draft posted to Telegram by a scheduled task must be complete body text that the user can select all and paste into a social platform with one click: information, judgments, and links written into the sentences; do not use 账本 jargon like this; do not include status, scores, save paths, "today's picks," or send out the entire Obsidian working draft. Do not fear writing long; fear writing messy—if there is material, write it out, one center per paragraph, in order; do not compress it into an outline just for neatness, and do not pile up scattered points.

---

I. Writing principles

Core goal

Make readers truly understand, be able to use it, and know the boundaries—not make readers think the author is very knowledgeable.

Six foundations

1. Engineer's perspective before emotional perspective: first discuss the problem, system, tools, and path, then discuss feelings and attitudes.
2. The author must truly be present: the article should show traces of a real workflow—why you encountered it, how you observed it, what tools/traces/commands/code paths you used, which step is most easily misjudged, and how you made your judgment.
3. Strong sense of structure; headings speak for themselves: readers should know the skeleton of the whole article just by scanning the headings.
4. Clear judgment, but the basis and boundaries must be explained: after giving a judgment, you must follow it with the basis, conditions, and scope of applicability.
5. Technical expression dares to be concrete: tool names, module names, class names, track names, parameters, versions, paths, and commands should all be written concretely.
6. Restrained ending; no empty elevation: technical articles just need to conclude; do not force elevation.

Information density

The goal is not "every sentence is packed," but "every sentence advances understanding."

• Each paragraph does only one thing: define, explain the mechanism, show evidence, or make a judgment; do not stew everything together.
• In the middle of high-density explanatory paragraphs, insertshort conclusion sentences/lists/charts/code observation points, to let readers breathe.
• Do not stuff more than 4 new concepts in a row; split paragraphs when necessary.
• The core viewpoint appears only 2 times in the whole article: definition + summary. Middle paragraphs use it directly and do not repeatedly explain it.
• A paragraph whose deletion does not affect understanding is "correct nonsense"; delete it.

Breathing room

Breathing room is not lyricism; it is cognitive load control:

• Follow a long explanatory paragraph with a short judgment.
• Give the big picture before complex mechanisms.
• Before a long code block, first say "focus on which lines."
• Add reader guidance at key points, for example:先记住一个结论:... / 到这里,A 和 B 的区别已经清楚。

Readability takes priority over superficial completeness

Expansion order:What the problem is → why it's worth reading → first build the overall picture → then drill down into details → finally give the judgment and boundaries. Not everything has to be explained all at once; explain in the reader's order of understanding.

---

II. Article Structure

5 common types of long-form articles

1. Technical deep dive/series analysis: explain the mechanism, observation methods, and analysis path. Structure: problem definition → background concepts → system flow → trace/code/diagrams → practical recommendations.
2. Tool in practice/architecture retrospective: explain why it was designed this way, how it was implemented, and what pitfalls were hit. Structure: origin → key decisions → solution breakdown → trade-offs → boundaries.
3. FAQ/Q&A: explain thoroughly, one by one, the questions readers care about most. Structure: question list → conclusion for each question → evidence/misconceptions/boundaries.
4. Methodology/industry observation/judgment-oriented: distill scattered experience into a judgment framework. Structure: real-world problem → author's judgment → break down dimensions → counterexamples/costs/boundaries.
5. Tool experience/reading/community/people: has a personal touch but still delivers practical value. Structure: origin → content/tool/viewpoint → author's additional understanding → recommendation/summary.

Default skeleton

【开头】直接交代问题、场景、文章任务
  ↓
【背景】为什么值得聊,读者能带走什么,需要哪些前置知识
  ↓
【主体】按 3 到 8 个板块展开,每块只解决一个问题
  ↓
【判断】把局部观察提炼成更高一层的理解
  ↓
【结尾】压缩结论、补边界、给后续阅读或行动建议

Opening

Within three sentences, three things must be accomplished: what this article is about, why it's worth reading, and what readers can take away after reading it.

Four commonly used openings:

• Series positioning type:本文是 XXX 系列的第 N 篇,主要讲 YYY。
• Recent event/reader feedback type:上一篇发出去之后,大家最常问的是...
• Cognitive correction type: first say how you thought before, then say what you found after actually using it.
• Judgment-first type: give the judgment at the beginning, then expand on the reasons and boundaries.

Opening taboos:

• Don't start with "in this era" or "with the development of technology".
• Don't talk about the broad background first and then slowly approach the topic.
• Don't lead with a correct but empty platitude as a hat.
• Don't turn a sense of table of contents into a sense of report.

Body

• One paragraph, one meaning: each paragraph undertakes only one task; don't do 3 things at the same time in one paragraph.
• Give the panorama first, then drill down: overall picture → key modules → trace/code/data → conclusion.
• Guide the reader at key nodes:先建立整体图景。 / 到这里先记住一个区别。 / 下面再看这个结论是怎么来的。
• Sequence design: put the baseline first, then the advanced examples, and finally the example that can most rewrite understanding.
• Division of labor between summary and details: if there are two sections, "summary" and "expansion", the summary only points out conclusions (2-4 lines), and the expansion is responsible for details. Don't write the same content once in each place.
• Series articles don't restate: concepts already defined earlier can simply be referenced later, not expanded again.
• When imitating others, imitate structure, not sentence patterns: what is borrowed is the way judgments are organized and the order in which evidence is arranged, not surface sentence patterns and historical formatting noise.
• Project rules don't get mixed into general rules: project-specific terminology, version presentation, brand tone, and information architecture go into project override rules, not into general writing standards.

Sentence patterns and rhythm

1. Say it directly first, then expand: say the central point in the first one or two sentences; don't beat around the bush.
2. Long sentences carry information, short sentences hammer it down:Long sentences set up the background/boundaries/subject; short sentences deliver the judgment.
3. Do not use first person:Do not write "I think"/"I suggest"/"I usually". Give the conclusion or steps directly.
4. Real details may be borrowed; a performative feel may not:Hesitation, trade-offs, and pitfalls you have stepped in may appear; intense emotional outbursts, internet catchphrases, and a dramatized bit feel may not.

Ending

Prioritize four ways to close:

1. Close with a single judgment.
2. After the main text, give references/further reading.
3. Give the reader the next action.
4. Echo the opening question once; do not create a literary loop.

Ending no-gos:

• Do not suddenly elevate to values.
• Do not write the conclusion as a slogan.
• Do not pretend to have an open ending while actually saying nothing.
• Do not vaguely restate the whole text again.

---

III. Banned words and sentence patterns

For complete rules, see references/style-rules.md、references/less-ai-tone.md、references/copy-editing.md、references/document-style-guide.md、references/chinese-copywriting-guidelines.md and references/human-feel.md. Before writing, rewriting, or quality checking, you must read them as needed.

For polishing/removing AI flavor, first read references/less-ai-tone.md: reversal tone, excessive enumeration commas, adjacent sentences with the same structure, reveal-style dashes, colons in prompts/idle sentences, ordinal-number subheadings, personified metaphors, generalizations covering data, five kinds of translationese, zero subject at paragraph start. At the author level, also handle: banned words, meaning inflation, imagined-reader errors, redundant confirmation adverbs, dangling verbs in technical drafts, structural metanarrative, synonym rotation, affectation, social-director sentences. Chinese technical documentation sentence patterns follow the adopted Ruan Yifeng draft; Chinese-English typography follows the adopted Typography Guide draft.

Articles on Android, performance optimization, Perfetto, and system mechanisms must also read references/android-terminology.md. In such articles,渲染链路、输入链路、Binder 调用链、BufferQueue、fence and other words may be accurate terminology and must not be mechanically replaced just because they hit a jargon lexicon.

---

IV. Presentation standards

Code

1. A "purpose sentence" must precede a code block: state what this section is meant to prove, where the reader should focus, and what conclusion they should reach after reading.
2. Code blocks must be readable: use standard Markdown code blocks and mark the language; naming/indentation/line breaks follow the language style guide.
3. Omissions are allowed but must be explicit: mark them with comments in that language; do not use vague .... For example // Several unrelated lines are omitted.
4. An "explanation sentence" must follow code: explain why this point is critical, how it corresponds to the conclusion above, and how the reader can observe it in practice.
5. Handling large code blocks: keep only the skeleton and critical path in the main text; put overly long code in a repository/Gist/appendix.
6. Code quality: provide a runnable version if it can run; if it cannot run, clearly state that it is "illustrative/pseudocode/excerpt"; do not fabricate nonexistent APIs/class names/method names.

Data

1. First decide the form of expression: if one sentence can make it clear, use text; for a small amount of comparison, use a list; for multi-metric comparison, use a table; for trends/fluctuations, use a chart; for temporal relationships, use a flowchart.
2. Data must have a reference point: every number must be supplemented with units, test conditions, comparison baseline, whether it reproduces stably, and sample scope.
3. Tables are not dumping grounds: include only the fields readers need to compare horizontally.
4. Charts are not decoration: they must answer one clear question.
5. Conclusions must connect back to the data:A sentence explaining what this set of data supports/does not support must be added after the chart/table.

Lists

**Core principle: a list cannot be a table of contents; it must be content.** Each list item must carry its own information increment; after reading the item, the reader knows "what this is / why it matters / how to use it."

❌ Forbidden phrasing:

- threads
- slices
- counters

✅ Correct phrasing:

- threads:按 tid 分组的线程轨道,用于定位主线程、RenderThread、Binder 线程的执行时间
- slices:函数调用的时间区间,颜色深度表示调用栈层级,用于定位哪个函数耗时长

Test:If you delete the description after a list item and leave only the noun, will the reader know less? If not, the description is not sufficient.

Charts

Chart type	Tool	Code fence	Applicable scenario
Flowchart/sequence diagram/state machine	mermaid	```mermaid	Rendering pipeline, VSync timing, state transitions
Layered architecture diagram	architecture	```architecture	System architecture, module layering
Data charts (bar/line/scatter/heatmap)	vega	```vega-lite	Frame rate curves, power consumption comparison, temperature trends
Complex dependency/call graphs	graphviz	```dot	Class inheritance, Binder call chains, module dependency trees
Info cards/timelines/comparisons	infographic	```infographic	Optimization effect comparison, tool ratings, methodology overview
Mind maps/knowledge graphs	canvas	```canvas	Knowledge system structure, concept relationships

Selection principle: if mermaid can do it, don't use graphviz; for data comparison prefer vega; for architecture layering prefer architecture; for WeChat official account articles prefer mermaid and infographic (good rendering compatibility).

Omission boundaries for architecture diagrams:When drawing sequence diagrams/architecture diagrams, you can omit decoration and same-layer details, butyou cannot omit the key intermediate layers that the reader follows the trace through. Test: does this node have an independent thread/counter/slice in the Perfetto trace? If so, it cannot be omitted—the reader will use the diagram to compare against the trace, and if they can't find the corresponding object, they will misunderstand it as "jumping directly across." Before drawing, ask: "What keywords will the reader look for when comparing this diagram against the trace?" The nodes corresponding to those keywords must all appear.

Terminology

• English words with established Chinese translations must be converted to Chinese(translationese pattern four). AI-generated Chinese often leaves English as-is—context, state, cache, claim, and the like—and the reader has to switch in their head each time: "context → 上下文," "claim 更硬 → 判断说得更重." Switch seven or eight times in one paragraph, and reading becomes tiring.
  • Anything with an established translation must be translated: 上下文 (not context), 状态 (not state), 缓存 (not cache), 断言 (not claim), 运行时, 协议层, 契约层.
  • Terms still being contested keep the English: prompt, embedding, tokenizer, harness, agent, etc.—these have not yet converged on a common translation in Chinese technical circles.
  • Test: is there a unified term for discussing this concept in Chinese circles? If so, switch to Chinese; if not, keep the English. The premise for keeping English is "Chinese circles have not yet agreed on a translation," not "the writer doesn't want to translate."
• One exception: English that has become a proper noun/identifier is kept—Android, Perfetto, VSync, Binder,trace_processor, Workflow, Agent (when used as the name of a specific component in frameworks such as RN/LangChain), etc.
• For Android articles, first judge terminology based on system objects and observational evidence. Words that can correspond to source code classes, system services, threads, trace tracks, slices/counters, or buffer/fence states should be treated as domain terminology; those without specific objects and boundaries should be treated as jargon.
• Only correct visible terminology in the text; do not mechanically alter code, fields, paths, URLs, trace names, thread names, counter names, or external source quotations.
• For a new concept appearing for the first time, first give a one-sentence plain-language explanation, then expand.
• Do not sacrifice precision for "plainness" — do not explain a term as another even emptier term.

---

V. AI Collaboration Standards

What AI is good at

• Organizing materials, outlines, and tables of contents
• Expanding existing viewpoints into a more complete structure
• Providing multiple explanation versions to help choose the easier-to-understand one
• Completing readability check items, finding jargon/repeated sentences/AI-flavored sentence patterns
• Assisting in organizing tables/lists/comparison matrices
• Expanding existing paragraphs from an established angle

What AI cannot do on the author's behalf

• Deciding the article's core angle
• Fabricating first-hand experience/experiments/trace observations/performance data
• Taking on technical correctness on the author's behalf
• Making final trade-offs and judgments on the author's behalf
• Pretending it actually ran in the author's engineering environment

Collaboration workflow

人:给出主题、读者对象、自己的判断、真实经历、关键证据
  ↓
AI:整理结构、补参考资料、提出可读性优化方案
  ↓
人:补一手细节、删错的、改判断、压风格
  ↓
AI:按四层质检做检查,指出具体问题
  ↓
人:终审,确认准确性、边界、可发布性

Must run: post-writing quality check is not an optional step

The first version generated according to this skill can only be considered a draft and cannot be directly treated as a release manuscript. Especially for tasks such as long-form WeChat Official Account/Zhihu articles, technical methodology, and interpretation of foreign viewpoints, the model will naturally slip back into high-frequency argumentative sentence patterns such as "not X, but Y," "not only X, but also Y," and "truly/actually/in fact." Even if the structure and content already conform to this skill, a round of rule scanning and hard fixes must still be run before delivery.

Before delivery, at least check and fix:

• 不是[^。\n]{0,25}而是|不只是[^。\n]{0,25}还|并非[^。\n]{0,25}而是|不仅仅是[^。\n]{0,25}更是|与其说
• 真正|实际上|其实|根本|彻底|确实 High-frequency adverbs; if the cumulative count of a single word is too high, compress it; delete all with no incremental information
• 最值得看|最值得|值得一看 Evaluation openers that users explicitly dislike, etc.
• 把画面|把卖点写成|把评测拆|叙事转到|官网把|跳得更|升幅大 Institutional personification/empty comparisons; when hit, change to "who, number, compared with whom"
• For Chinese typography, follow references/chinese-copywriting-guidelines.md Scan spaces between Chinese and English/numbers, spaces around units, and repeated punctuation; follow references/document-style-guide.md Scan double negatives, "reduce N times," and heading level skipping. Do not treat passive sentences themselves as unacceptable
• For the corpus layer, follow references/less-ai-tone.md Scan for revisionist tone, colon with empty spinning sentences, paragraph-initial zero subject, overly long premodifiers, "when...," topic shell at the front, sentence-initial "however/therefore/in addition," and restatement with "this means." Do not change sentences that are not hit
• Structural meta-narration, imagined reader errors, meaning inflation, and casually adding analysis. In the main text, "first... second..." and questions should not be deleted as AI flavor
• For social posts, additionally follow references/social-output-gate.md Scan once: changelog summaries, negative openings,一、二、三 feature parallelism, slogan endings, forced celebrity associations, director sentences, empty comparisons
• Read-aloud test for social posts: for each sentence ask, "Would friends say this to each other?" If not, rewrite it, not just swap words

The work order is fixed as: first produce a complete draft according to the skill → immediately scan → hard-fix sentence patterns and prohibited words → spot-read key paragraphs → then deliver a publishable version. Do not mistake "written according to the skill" for "passed the skill quality check."

Hard rules

• Do not treat AI-generated "looks real" as "real"— must verify.
• AI must not be allowed to automatically fill in experimental conclusions that do not exist。
• AI's smooth phrasing must not be served up as-is—it must be rewritten a second time.
• One round of generation must not be published directly。
• Do not copy others' frameworks/views without citing the source。
• Published drafts are for readers only and must not leave editing traces:The main text must not contain writing-process records such as "this version"/"the previous draft"/"revised as requested."

---

VI. Quality Inspection System

For the complete four-layer quality inspection rules, see references/quality-gate.md. After writing, check layer by layer according to L1 hard rules, L2 readability, L3 content depth, and L4 human feel; L4 must include the references/human-feel.md checks for concreteness, meaning inflation, synonym rotation, format overexertion, and affected expression, as well as the references/less-ai-tone.md corpus layer's 11 items. Social drafts must also pass references/social-output-gate.md. Quality inspection only outputs a report and does not automatically modify content; if a social draft fails quality inspection, rewrite the main text, then submit a publishable version. Refinement tasks rewrite according to the whitelist; do not expand the "AI tone" in the quality inspection report into the scope of rewriting.

---

VII. Refinement mode

When the user requests "refinement," "polish but do not rewrite," or "only fix AI tone," first read references/less-ai-tone.md, then read references/refinement-mode.md and references/human-feel.md. Refinement only changes wording, sentences, and format; it does not change structure, factual judgments, or add new arguments. Sentences not hit by the corpus layer whitelist are retained verbatim.