Blog Writing Notes: KernelGen Optimization Posts

这份笔记记录 2026-06 的 KernelGen 优化博客写法，方便后续写同类文章时复用。

基本语气

• 语气保持谦逊、复盘式，不写成“教程口吻”或“胜利宣言”。
• 先解释问题为什么值得做，再进入代码；读者不应被迫一开始就面对 kernel 细节。
• 少用“不是 X，而是 Y”这种说教式句式。可以用“更准确地说”“从这个角度看”“这里有一个容易忽略的点”来承接。
• 可以写成绩，但成绩要服务于技术判断：说明约束、边界、失败尝试和验证方法。
• 对未能由仓库证据直接证明的事实，写成阶段性观察或现场结果，避免过度断言。

文章结构

• 开头第一屏给出官方题面入口，并直接显示 URL；不要把比赛链接藏到中段。
• 第一段说明这篇文章记录什么、为什么值得记录，以及文章保留了哪些材料。
• 公开文章只写平台题号、函数名和可复现的技术事实；不要解释本地目录名、内部任务编号和平台编号之间的映射。
• 从基础概念讲起：Attention、SwiGLU、quantization、tile、memory bandwidth 等先给读者建立计算模型。
• 中间用公式拆开算子：输入、输出、形状、核心等式、量化规则、正确性约束。
• 之后再进入实现：baseline 的直观写法、瓶颈在哪里、我们采用的分解、平台分支。
• 结尾写“值得保留的经验”和“失败尝试”，避免只有结果没有过程。

数学与代码

• 公式用 MathJax，变量尽量与代码一致，例如 $M,H,E,T$、group_size=128。
• 避免把长代码整段贴出；只贴解释某个技术选择所需的片段。
• 对核心 kernel 的解释按数据流写：load -> compute -> reduce/quantize -> store。
• 对量化问题要明确 scale、rounding、tolerance。若语义依赖 BF16 roundtrip，必须说清楚。
• 讲 tile 时要说明 tile 同时服务于哪几个约束：并行粒度、寄存器压力、访存形状、量化分组。

排版

• 默认英文版，提供中文切换；中文版本可以更自然，但结构要与英文一致。
• 标题不用编号，避免“1. 2. 3.”式目录感。
• 重要概念用 notice--info、notice--primary、notice--warning 这类提示块，但不要过密。
• 表格用于固定 shape、平台差异、优化收益和失败尝试；不要把叙述都压进表格。
• 长 URL 放在开头入口卡片中，移动端需要 overflow-wrap: anywhere。
• 自动目录由站点脚本从 h2 生成，不要手写目录。

取证与发布

• 写作前先读当前代码、notes、submission log、tests，不只依赖聊天记忆。
• 如果仓库状态是 dirty，要在文章材料中区分“已提交结果”和“未提交实验”。
• 优化过程按“定位到的问题 -> 解法 -> 收益”组织。提交记录和日志只作为证据来源，不作为文章主线。
• 发表前至少跑 bundle exec jekyll build。
• 涉及页面布局或语言切换时，用 Playwright 检查桌面和移动端。
• 发布后确认 GitHub Pages 线上 HTML 已包含新文章或关键改动。