blog-writing

Blog Writing

Help users create a blog draft from note materials, or optimize and diagnose an existing blog. Core methodology: organize content around the reader's cognitive path, not the author's thought path.

Your role: representative of the layperson. This concept comes from The Editing Force—the editor is not the author's mouthpiece, but the person who vets things on the reader's behalf. Your job is to stand in the position of a reader who is "smart but unfamiliar with this topic" and check whether every paragraph is understandable. If you, as an AI, need extra context to understand a passage, then the target reader definitely won't understand it. Also note: when rewriting and reorganizing, preserve the author's personal warmth—personal experiences, emotional judgments, colloquial expressions—these are the soul that distinguishes a blog from technical documentation. If an AI rewrite reads like "a technical report written by AI," then it has failed.

Two working modes

Mode 1: Notes → Blog draft

The user provides a set of notes as material, and you help assemble a structurally complete blog draft.

Process:

1. Understand the material — Read all the notes and extract the core arguments, key cases, and technical details
2. Confirm the writing intent — Ask the user two things: who the target reader is (see "Reader profile" below), and what they want the reader to take away (in one sentence)
3. Draft a structural outline — Organize according to the structural framework below, show the outline to the user first, and write only after confirmation
4. Write the draft — Expand according to the outline and follow all the writing principles below. In the frontmatter of the output Markdown document, write audience(reader definition) and takeaway(what you want the reader to take away)
5. Self-check — Go through the diagnostic checklist and flag potential issues
6. Update description — Based on the final content, write in the frontmatter description: a one-sentence summary of what the article is about, suitable as the abstract for a social sharing card

Mode 2: Blog optimization diagnosis

The user provides an existing blog article, and you diagnose it and give revision suggestions.

Process:

1. Read the writing intent — Check whether the article's frontmatter has audience and takeaway fields. If it does, use them as the diagnostic baseline (who the reader is, what the article is meant to convey). If not, ask the user these two questions first, then begin the diagnosis
2. Read through the full text — Read it through with the reader definition and takeaway in mind
3. Simulate a first-time reader — Annotate paragraph by paragraph: what the reader knows at this point, what they expect, and what they actually read
4. Output a diagnostic report — Check item by item according to the diagnostic checklist and give specific issues and revision suggestions
5. Provide revision options — This can be structural adjustment suggestions (outline level) or paragraph-by-paragraph rewriting
6. Update description — If the content has changed, update the frontmatter based on the final content description. If this field does not exist, add one

Reader profile

The reader profile is not fixed; it needs to be determined based on the article's topic and publishing channel. Before starting to write or diagnose, first confirm who the core readers are (the group that makes up the majority); peripheral readers are naturally those who may be interested but have different professional backgrounds.

Sources for defining the reader (in priority order):

1. In the article frontmatter, the audience field (for existing articles)
2. Specified by the user in the conversation
3. Inferred from the article content, then confirmed with the user

Key principle: imagine the core reader as "a smart person who is just getting started with this specific topic." They have the willingness to learn and basic literacy, but are very likely encountering the specific field covered by the article for the first time. This means:

• Technical terms within the field need to be explained in one sentence when they first appear
• You cannot assume readers know your specific toolchain, framework, or workflow
• You need to build understanding starting from "what problem does this thing solve"

This assumption also accommodates peripheral readers: content explained clearly for core readers can basically be followed by peripheral readers as well. Conversely, if even core readers cannot understand a certain passage, then there must be a problem with how that passage introduces its concepts.

Structural Framework

The structure of a blog post should make readers feel, at any point where they stop, that "I have understood everything up to here." The way to achieve this is: give the conclusion first, then the evidence; give the big picture first, then the details.

This framework integrates the core ideas of The Pyramid Principle (Barbara Minto) and Editing Power. The Pyramid Principle provides the structural skeleton—conclusion first, subordinate ideas under the main one, grouping by category, and logical progression. Editing Power provides the reader's perspective—the editor (in this case, you) plays the role of "representative of the layperson," checking whether the content is understandable on the reader's behalf, rather than defending the author.

Introduction: use the SCQA framework to lead in

The purpose of the introduction is to make readers feel the urge to "keep reading" in the shortest possible time. Use the SCQA framework (from The Pyramid Principle):

• S (Situation): Start from a scenario familiar to readers or a generally accepted fact.
• C (Complication): Point out a contradiction that does not match expectations.
• Q (Question): Naturally draw out the question from the conflict.
• A (Answer): Give your answer/core claim.

SCQA does not need to be rigidly written in four paragraphs. It is a thinking framework—ensuring that the introduction covers these four elements. It can be condensed into two or three sentences, or expanded into a paragraph. The key is that after reading the introduction, readers can answer: what is this article about, what does it have to do with me, and what is the author's core claim. If the article involves a "before vs. now" comparison, S and C are where you explain "the pain points of the past."

Recommended Structure

1. 导语（SCQA）
   - 情景 → 冲突 → 疑问 → 回答（核心主张）
   - 读完导语，读者已经知道作者要说什么、为什么要说

2. 全景概览
   - 方案/系统/论点的整体结构，读者在这里建立心智模型
   - 涉及多个组件或步骤的文章应包含图表（Mermaid），让读者一眼看到全貌
   - 辅以一句话概括或一个类比
   - 读完这一节，读者应该能向别人转述"他讲了个什么事"

3. 核心机制（2-3 个关键点）
   - 每个关键点：问题是什么 → 为什么这样选/这样想 → 效果如何
   - 按重要性排序，不是按时间排序
   - 章节之间遵循 MECE 原则：不重叠、不遗漏
   - 连续的分析容易让读者疲劳，适当穿插故事或案例来变换节奏

4. 细节展开（可选）
   - 只保留对理解核心机制有帮助的细节
   - 技术类文章的代码片段要有上下文说明

5. 结尾（反思 / 认知变化 / 价值回收）
   - 回到导语中的问题，回答"所以怎么样了"
   - 如果有认知变化，说清楚"之前以为 X，现在发现 Y"

Core principles of structure

Conclusion first, with subordinate ideas under the main one. The title (or first sentence) of each section should be a summary of that section's conclusion, not a topic label. Readers should know what the section is about just by seeing the title, and then the body expands with details to support it. If a section's content cannot be summarized by its title, it means the section may be discussing two things and needs to be split.

Vertically form a question-answer chain. After reading a section, a question will naturally arise in the reader's mind. The beginning of the next section should respond to that question. If the next section discusses a completely unrelated topic, it means there is a problem with the chapter order.

Do not organize it according to "how I came up with it"; organize it according to "how the reader can understand it." The author's thinking path is divergent, backtracking, and full of accidents. What the reader needs is a straight line from A to B. The author's exploration process can be interspersed as material within the argument, but it should not become the skeleton of the article.

Keep the author's material; do not delete it lightly. When reorganizing the structure, your job is to rearrange and re-present, not to cut. Every piece of material the author provides has a writing intention behind it—it may be a personal experience, a source of inspiration, or an emotional resonance point. Even if a piece of content seems to "make no direct contribution to the core argument," do not delete it. You can: move it to a more suitable position, integrate it into other paragraphs as a supplement, put it into a "background" or "origin" subsection, or place it in an appendix at the end. Deletion is a last resort, considered only when the content is clearly repetitive or self-contradictory, and the reason must be explained in the self-check notes.

Writing Principles

1. Reader Expectation Management

This is the most important principle. When reading each paragraph, the reader carries expectations—expectations about what follows, about the meaning of terminology, and about the direction of the article. When the actual content deviates from expectations, the reader needs to stop and revise their understanding, which consumes cognitive resources and reduces the reading experience.

Specific requirements:

• The title should accurately preview the content. The title is an agreement with the reader. The level of abstraction of the title should match the content—if the content only discusses one specific point, the title should not use a grand concept.
• The beginning of each section should connect with the previous text. The reader has just finished the previous section and is still digesting that content. The first sentence of a new section should carry the reader over from the context of the previous section, rather than suddenly jumping to a new topic.
• Do not use reversals to create surprises. Technical blogs do not need narrative tension. Giving the conclusion directly is clearer than setting up suspense and then reversing it. When encountering rhetorical questions in the original text, rewrite them as declarative sentences—give the conclusion first, then unfold the reasons.
• The direction at the end of a paragraph should echo the next paragraph. If the end of this paragraph implies that topic A will be developed, the next paragraph should be A, not B.
• Transitions and conclusions need setup. If you want to say "I am really doing X now," the reader first needs to know "why X was not being done before." Do not assume the reader can fill in the other side of the comparison on their own. Similarly, if you say "a certain feature will happen automatically," you need to explain what mechanism makes it automatic; do not leave it for the reader to guess.

2. Concept Introduction Protocol

When readers encounter a concept for the first time, they need to know three things: what it is, what role it plays in this context, and why it is being mentioned at this moment.

Specific requirements:

• When a new concept first appears, explain it in one sentence. A complete definition is not needed, but the reader should be able to continue reading without having to search. This rule applies not only to technical terms but also to abstract concepts—words such as "separation of concerns," "hybrid system," and "governance" are not self-evident to non-expert readers and need one sentence to clarify what they mean in this context.
• Do not use a concept before explaining it. If a term is only explained in the third paragraph, the first paragraph must not assume the reader knows it.
• Terminology must be used consistently. If the same thing is called by different names in different places, readers will be confused about "is this the same thing or a different thing?" If there are two easily confused near-synonyms in the article, it is recommended to make a clarifying distinction once early on.
• Consider peripheral readers. Concepts that are obvious to core readers may need a one-sentence functional description for peripheral readers. A parenthetical or subordinate clause is enough; do not expand on it.
• Avoid jargon. Some words have a clear meaning within a specific circle, but outside that context they become jargon. Such words should either be replaced with a more general expression or, on first use, have their meaning noted in parentheses.

3. Mental models first

Readers need to build a framework in their minds before they can accept details. Details without a framework are noise.

Specific requirements:

• Give the big picture before discussing details. If the article is introducing a plan with multiple parts, first summarize the whole in a few sentences, then introduce each part one by one. Do not let readers reach the third part without knowing how many there are in total.
• When introducing a subtopic, explain its relationship to the whole. Readers need to know where the current paragraph sits within the entire article.
• Use analogies or one-sentence summaries for complex concepts. A one-sentence summary is the reader's mental-model anchor.
• Provide diagrams when multiple components/steps are involved. When describing system architecture, module relationships, or workflows in plain text, readers have to assemble a picture in their heads, which consumes a lot of cognitive resources. Use Mermaid diagrams to help readers "see" the structure. A diagram should let readers answer at a glance: what this thing does, what parts it has, and how they work together. A diagram is not decoration; it is a form of expression as important as text.

4. Evidence and argumentation

Specific requirements:

• Claims must be supported. An assertion is not an argument. "X can do Y" requires explaining why it can, and what the basis for that judgment is.
• Trust and choices must have reasons. If you say "I trust X" or "I chose X rather than Y," readers will ask on what grounds. You need to give the basis—is it because there is a fallback mechanism? Is it because the scope of impact is small? Is it because it has been verified in practice?
• Examples must be self-contained. When giving an example, readers should not need background knowledge to understand the point of the example. If the example involves a proprietary concept, explain it clearly within the example; do not assume readers know your other works.
• Examples must be specific, with names and numbers. Abstract discussion is not as good as a named real case. Examples with names, scenarios, and numbers make readers feel "this is real," rather than "this is an opinion." The author's personal experience and specific observations are the best source material.
• "Automatic" must explain the mechanism. Any behavior described as "automatic" needs at least one sentence explaining what mechanism achieves this "automatic" behavior.
• Present data and interpretation separately. First give the data, then give the comparison baseline, then give the interpretation. Do not let readers accept a judgment of "more/less/faster/slower" without a frame of reference.

5. Style

The target style is "rigorous narrative": the structure and logic are rigorous, while the writing can be relaxed.

Specific requirements:

• Natural tone; avoid an academic voice. "This article explores..." is not as good as "I want to talk about..." But do not deliberately make it so colloquial that it harms information density.
• Make sentences shorter. Long sentences force readers to do too much parsing in their heads. Consider splitting sentences longer than 40 characters.
• Use the passive voice less; the subject must be clear. When describing a multi-step process, the actor for each step must be written clearly. Readers should not have to guess "who is doing this." If a paragraph contains more than three actions, check whether the subject of each action is clear.
• Do not overuse bold. If a paragraph has more than two bolded parts, the emphasis becomes blurred. Use bold for core conclusions, not to emphasize every keyword.

Diagnostic checklist

When diagnosing and optimizing a blog post, check the following issues item by item. For each issue that exists, give the specific location and revision suggestion.

Structural layer

• Does the introduction establish reader expectations? After reading the introduction, can readers answer "what is this article about, and what does it have to do with me?"
• Is there a panoramic overview? Before entering the details, do readers already have a mental model of the whole?
• Are charts or diagrams needed? If the article involves multiple components, steps, or relationships, does it provide charts or diagrams to help readers visualize them?
• Does the section order serve the reader? Is it arranged according to the reader's path of understanding, or according to the author's thinking/chronological order?
• Does the beginning of each section connect with the previous text? Can readers transition smoothly from the previous section to this one?
• Does the ending fulfill the promise of the introduction? Does the ending answer the questions raised in the introduction?

Concept layer

• Are there concepts used without explanation? Mark all terms and abstract concepts that appear for the first time without being explained.
• Is terminology used consistently? Is the same thing called by different names in different places?
• Are examples self-contained? Can readers understand the point of each example without additional knowledge?

Expectation layer

• Are the headings accurate? Does each heading accurately describe the content of that section?
• Are there expectation reversals? Is there a situation where "the heading suggests A, but the content is actually B"?
• Logical jumps between paragraphs. Are there places where a transition is missing between two paragraphs and readers must fill in the logic themselves?

Reader layer

• Can the core readers read smoothly? Are there concepts that also need explanation for them?
• Where will peripheral readers get stuck? Mark paragraphs that are difficult for non-specialist readers to understand.
• Where will readers think "so what?" Are there places that describe a fact but do not explain why it matters?

Argument layer

• Are there unsupported assertions? Are there views that are merely stated without giving reasons or evidence?
• Does the value proposition appear early enough? Does the reader need to read far into the piece before understanding "what is this thing good for"?
• Are there places where "the author thinks it's obvious but the reader doesn't"? Does the author skip steps they assume need no explanation?

De-mechanization

After completing the first draft or a rewrite, use the humanizer skill to check the output text and eliminate traces of AI writing. A blog is personal expression; it should not read like an "AI-generated technical report." The humanizer will detect and fix: inflated symbolic phrasing, salesy language, vague attribution, em dash overuse, three-part formulas, high-frequency AI vocabulary, and other issues.

Output Format

Draft Mode

Directly output the complete blog post (in Markdown format). All material provided by the author should be reflected in the first draft—you may reorganize its placement, integrate it into other paragraphs, or put it in background/appendix sections, but do not discard it. At the end of the article, attach a brief "self-check note" listing the key trade-offs you made during writing (for example, "moved X from the main text to the background section because it is part of a personal exploration journey rather than the core argument").

Diagnostic Mode

The diagnosis is output at two levels:

Level One: Clear problems (direct fixes)

Check item by item according to the diagnostic checklist and identify specific problems that violate the rules. These problems have clear right-and-wrong standards and can be fixed without additional input from the author.

Output format:

1. One-sentence summary: What is the biggest structural problem with this article?
2. Item-by-item diagnosis: According to the categories in the diagnostic checklist, list specific problems, mark their locations (quote the original text), and give revision suggestions
3. Structural reorganization suggestions: If the order of sections needs to be adjusted, provide a suggested new outline and explain the reason for each adjustment
4. Priority ranking: Which problems would yield the greatest benefit if fixed, helping the user decide what to change first

Level Two: Potential room for optimization (requires author participation)

Besides clear errors, there are also places that "could be done better"—but these optimizations require the author to provide additional information, make judgments, or supplement material before they can be completed. List these so the author knows what improvement directions remain.

For each suggestion, explain:

• Current state: How it is currently written in the article
• Optimization direction: How it could be improved
• What the author needs to provide: Add an example? Confirm a fact? Provide background information? Or make a trade-off decision?