写附带可运行代码示例的技术文章和教程

## 像经验丰富的工程师给同事讲解那样写 写作时应像一位经验丰富的 engineer 正在白板前与同行共同解决问题：技术上准确、表达直接、态度温和，而且绝不拘谨。尊重读者的理解能力，但不要假定他们具备全部先验知识。明确说明什么有效、什么无效以及其中的原因。 如果能让读者成为协作者，就使用“我们”“让我们”等包容性表达。迅速切入重点，让示例承担大部分说明，并保持自信，但不要变成说教。 ## 从真实问题讲起，尽早展示可运行的代码 每个 section 开头用1到3句帮助读者确定方向，然后进入实质内容。用真实 task、failure 或运维负担说明 topic 的动机，不要诉诸抽象承诺。 在介绍 concept 的同时或紧接其后给出 code。优先使用真实、可运行的示例，而不是 pseudocode；先让读者看到实际行为，再解释关键机制。使用具体 tool、真实 command 和有代表性的 error message，不要含糊地指向某种通用 solution。 ## 段落简短，句子主动直接 每个 paragraph 尽量控制在3到4句。将密集信息放进 bullet 或 code block，不要堆成长篇文字墙。连接相关观点时，多用 `and` 或 `but`，少用 semicolon；短小的补充说明应使用 dash，不要层层嵌套 parentheses。 只要适用，就使用 active voice。instruction 使用 imperative mood，描述行为使用 present tense。在英语中，优先使用 `we'll`、`you're`、`it's`、`don't` 等自然 contraction；只有需要刻意强调时才使用完整形式。 ## 链接前置知识和相关主题，不过度解释 准确使用 technical term，并以自然方式引入。除非某个 term 确实需要解释，否则不要添加 glossary 式 definition。如果 topic 存在 prerequisite，应说明其名称并链接到相关材料。 将 cross-reference 用作 breadcrumb，把当前说明与前后 topic 连接起来。明确注明 tool、project 和人物的名称以给予 credit，并使用描述清楚的 inline link，不要写“点击这里”。当某个 tool 的 option 超过 article 能覆盖的范围时，将读者引导到该 tool 的权威 documentation。 ## 结合经验和利弊，明确给出建议 直接推荐 practice，并用经验、evidence 或具体 trade-off 支撑。不要层层添加保留措辞，削弱有用 guidance。讨论 alternative 时，应公平说明 benefit、cost 和适用条件。 谨慎使用 rhetorical question，并立即给出答案。可以用克制的 humor 或偶尔出现的俏皮表达增添个性，但不要变成 slang。尤其是在介绍有用的 workflow 或未来可能性时，应表现出有依据的真诚 enthusiasm。 `Let's look at...`、`The real difference is...`、`Pro tip:` 等可复用 transition 可以强化 voice，但只有在它们能推动说明继续前进时才使用。 ## 去掉空话和刻意装出来的随意口吻 公开内容中绝不要使用 profanity、emoji、冗长的个人 anecdote、memoir 式离题、slang 或刻意装出的随意语言。避免关于快速变化世界的 cliché、邀请读者“深入探索”的套话、空洞的结尾 platitude、`lol` 以及用 ALL CAPS 强调。 去掉 buzzword、没有传递信息的 filler sentence、过长的 introduction、不必要的 passive voice 和夸张措辞。在英语中，应使用 `use`，不要使用 `utilize`。不要写 `please note that` 或 `it is important to note that`，直接说明要点。不要过度解释目标读者按其水平理应了解的内容。 ## 统一标题和代码块写法，方便快速浏览 H1 仅用于 document title。major section 使用 H2，subsection 使用 H3。每个 code block 都要标明 language identifier，并优先使用读者能够运行的示例。 bold 可用于 key term 首次出现时，或在 list 中进行强调，但绝不要将整句设为 bold。italics 用于短小补充、作品 title 或轻度强调。horizontal rule 只能放在 closing 或 signature section 之前。 link 的描述应清晰，list 结构应保持平行，示例应靠近其支持的 text。始终一致地使用 Oxford comma。 ## 教程和博客文章按“问题、代码、下一步”的顺序组织 lesson 或 tutorial 应采用以下顺序： 1. 用1句话概述读者将学到什么； 2. 用不超过2到3句话提供 context 或 motivation； 3. 通过 code example 讲解核心内容； 4. 将 lesson 连接到相关 topic； 5. 邀请读者贡献、提问或继续学习。 blog post 或 article 应从一个简短的问题或 opportunity 开始，解释它为何在当下重要，通过 code、configuration 或 process 展开主要 walkthrough，探讨更广泛的 implication 或其他 use case，最后以面向未来的 summary 和参与邀请收尾。 ## 针对初学者和新工具介绍调整语气 向 beginner 解释 concept 时，应采用温和、耐心、协作的 voice。介绍 tool 或 workflow 时，应保持 enthusiastic 和实用，同时如实说明 limitation。推荐 practice 时要直接，并用经验支撑。 公平讨论 trade-off，并指出具体 advantage 与 disadvantage。谈论未来 plan 时，应保持有依据的 optimism。conclusion 应简洁，指向下一个有用 action，并让读者感到容易参与。 ## 最后检查代码示例和链接，并以下一步收尾 确认文章从实际问题开始，迅速进入真实示例，而且不只是断言，也给出说明。检查 prerequisite 和 cross-reference 是否齐全，technical term 是否准确，示例是否可运行，以及被点名的 tool 是否获得恰当 credit。 去掉 filler、不必要的 jargon、重复的铺垫，以及超出受众需要的解释。检查 heading、code block 的 language、link、emphasis、paragraph length 和 punctuation。最后以继续前进的方向结束：下一步尝试什么、要留意什么，或者从哪里继续学习。