Appearance
信息架构最佳实践 — 学习站点该怎么组织
本页回答一个问题：一个"从零实现 LLM"的学习站，页面该怎么分层，才能同时服务「按章学」和「随手查」两种模式。
为什么 IA 值得单独一页
学习站最常见的失败模式不是内容不够，而是同一个概念散落在五个页面、学习者不知道下一步该点哪里。目录像文件夹而不是路径，读到第三章就迷失。本页把别人的做法对照一遍，再落到本仓库的具体目录上。
一、四种文档类型：Diátaxis 骨架
Diátaxis 框架主张按"读者当下的意图"分目录，而不是按主题分目录。它识别了四种独立的需要：tutorials、how-to guides、technical reference 和 explanation（来自 diataxis.fr 的原文："four distinct needs, and four corresponding forms of documentation"）。
| 类型 | 读者当下的状态 | 写作目标 | 本站对应目录 |
|---|---|---|---|
| 教程 Tutorial | 我是新手，带我走一遍 | 学习导向（learning-oriented） | /chapters/ |
| 操作指南 How-to | 我有具体任务想完成 | 任务导向、给方向 | /examples/（实验重跑索引；旧 /labs/ 已并入，不再是顶级入口） |
| 参考 Reference | 我要查一个事实 | 信息导向、给事实 | /reference/ |
| 解释 Explanation | 我想理解为什么 | 理解导向、给语境 | /reference/core-map + 每章的公式小节 |
最常见的 IA 错误就是把四种类型混在同一个页面里——比如一篇同时"教你上手"、"给你一段代码"、"又解释原理"的文章。Diátaxis 强调这种混合会让每种读者都不顺手。
二、五个参考对象的 IA 模式
1. Karpathy nn-zero-to-hero — 严格线性、每讲一个 notebook
组织方式：lectures/ 目录下分主题子目录（如 micrograd/、makemore/），makemore/ 内有 part1_bigrams.ipynb 到 part5_cnn1.ipynb 五个分讲 notebook；每讲对应一个 YouTube 视频，必要时链接独立仓库（micrograd、makemore、minbpe）。
为什么有效：每讲都可以独立运行，"看完视频立刻动手"成为闭环；线性顺序与依赖关系一一对应，前一讲的输出是后一讲的起点。
可借鉴的一条：每一讲必须配一个可运行的入口（notebook 或脚本），不能只讲概念。
刻意不借鉴的一条：不照搬其"只对 YouTube 观众友好"的纯视频形态——本站要把文字版、练习、参考资料都内联到页面里。
2. Coursera / DeepLearning.AI — 周次线性、模块内可乱序
组织方式：课程拆成周次（Week 1/2/3），周次内把 Videos / Readings / Quizzes / Programming Assignments / Labs 明确分离。例：Andrew Ng《Supervised Machine Learning》Week 1 含 20 个视频、3 个 quiz、4 个无评分 lab（来自课程页直接读取）。
为什么有效：周次保证"按周学"的进度感；同一周内的 quiz 与 lab 互不干扰，可以各自独立完成。
可借鉴的一条：评估与内容分开——quiz 单独一组，lab 单独一组，绝不混进视频流。
刻意不借鉴的一条：不照搬其"周次锁定、必须按顺序解锁"的强线性机制——本站读者可以自由跳转。
3. Google Developers 文档 — Learn / Guides / Reference 分层
组织方式：导航顶层分为 Foundational courses、Advanced courses、Guides、Glossary；Glossary 再按主题（Agentic、Clustering、Generative AI 等）横切。Style Guide 自陈："Follow style guidance specific to your project... then follow this guide."（先项目规范、再本指南）。
为什么有效：标题写成任务导向（如"Do you have questions..."），读者扫一眼就知道这一页是不是他要找的；Glossary 让"定义一个术语"这件事有一个唯一定义页。
可借鉴的一条：单一事实源——一个术语只能有一个权威定义页，其余全部链接过去。
刻意不借鉴的一条：不照搬其覆盖 50+ 产品的横向广度——本站只服务"从零实现 LLM"这一条主线。
4. 3Blue1Brown — 一个概念一条主线、可视化先于公式
组织方式：每个视频就讲一个概念；站内有 /?topic=neural-networks 这种主题聚合页，也有 /?lesson=cross-entropy 这种精确章节锚点；章节标记支持跳读（来源：3blue1brown.com/topics/neural-networks）。
为什么有效：读者既可以顺序观看，也可以从某一章节精确切入；标题直接抛问题（"But what is a GPT?"）而非描述内容。
可借鉴的一条：章节标题写成问题，而不是写成"第 X 章：自注意力机制"。
刻意不借鉴的一条：不照搬其纯视频形态——本站以可点击、可搜索的页面为主。
5. Diátaxis — 按读者意图而非按主题分目录
组织方式：把文档分成"应用轨"（Tutorials / How-to / Reference / Explanation）和"理论轨"（Foundations / The map / Quality），先按读者想做什么、再按他想理解什么来分流。
为什么有效：读者带着意图来，目录直接回应意图；同一概念（如"梯度下降"）可以同时出现在教程（怎么跑）、参考（API）、解释（为什么）三个不同位置，互不冲突。
可借鉴的一条：顶级目录反映意图（"学"、"做"、"查"、"懂"），不是反映主题（"模型"、"数据"、"训练"）。
刻意不借鉴的一条：不照搬其四象限对称结构——本站把 explanation 并入每章小节而非平铺成顶级目录。
三、导航设计原则
- 顶级导航不超过 5 项（米勒短时记忆 7±2 的工程化取舍）。反例：把首页、学习、实验、参考、术语、论文、资源、关于我、捐赠 9 项都顶到导航栏。
- 每个页面回答"我从哪来、我该去哪"——必须有前置链接和后置链接。反例：一篇文章读完不知道下一步。
- 同一概念只有一个权威定义页（single source of truth）。反例："注意力"在 5 个页面里 5 种定义。
- 目录深度不超过 3 层（首页 → 分类 → 页面）。反例：把读者埋到 5 层路径里。
- 可运行的东西和可阅读的东西分开放。反例：notebook 链接散落在解释文章里。
- 标题用问题或动作，不用品类名。反例："第三章 反向传播"；正例："反向传播是怎么把误差送回前面的？"
- 评估与内容分离。反例：quiz 题混进讲义里；正例：quiz 是一组独立页面。
四、对本课程的 IA 建议
当前目录现状
仓库根目录 docs/ 下只有三个顶级入口：/chapters/（教程唯一正文，全书 21 章单序列编号，交互演示与动手实验都内嵌在章节页面里）、/examples/（教程实验的快速重跑索引，编号与章节一致，不重复正文）、/reference/（术语表/IA/论文/资源/核心知识地图/边界/口试，只做中立查阅）。旧 /labs/ 与 /cloud/ 已并入上述分类、退出顶级导航；少数页面（如 /labs/colab、/cloud/dry-run）因内容仍有效而保留，但无导航入口，靠各页顶部横幅说明归属。
全书按内容依赖排成单一编号序列，不再使用"周"框架：第1章是环境与权益审计，第2章是零基础 Python/数学坡道，第3–19章是从自动微分到 Capstone 的主线，第12、14–17章是真实 API/RAG/LangGraph/流式实战章，第20–21章是第二梯队扩展章（DeepSeek 专题、Subagent/Multi-Agent）。它们同属 /chapters/ 正文，不新增顶级入口。（历史说明：本站曾按"12 周课程 + 插入式字母周"组织，后重构为纯章节书籍结构——周编号与章节号的完整对应关系见仓库 docs/superpowers/specs/2026-08-18-book-restructure-design.md。）
三个顶级入口与下层关系
读者意图 → 应落到的页面
| 读者意图 | 落到页面 |
|---|---|
| 我是新手，从零开始 | /chapters/ 教程总览（零基础从第2章进） |
| 我想跟完某一章 | /chapters/01-setup 到 /chapters/21-multi-agent（含扩展章） |
| 我想重跑一个具体实验 | /examples/ |
| 我想看实验怎么搭环境 | /reference/setup（第1章环境审计的稳定入口） |
| 我想查一个术语定义 | /reference/glossary |
| 我想读一篇论文背景 | /reference/papers |
| 我想看延伸资源 | /reference/resources |
| 我想理解为什么这样做 | /reference/core-map |
具体改进建议（待办式）
- 每章页面底部追加"配套实验"区块——把对应的
examples/链接直接放进去，而不是让读者自己找。 - 术语表升级为唯一定义源——任何讲义里出现术语，第一次出现处统一链接到
/reference/glossary，避免在各章讲义里重复定义。 - "怎么跑"只留一份权威说明——环境、命令、Colab 注意事项由
/reference/setup（指向第1章）统一承载，旧/labs/已并入/examples/；/examples/只承载"跑什么、去哪重跑"（回链到对应章节的锚点）。✅ 已落地 - 新增"按读者意图选入口"的小组件——在首页顶部用三张卡片（学 / 做 / 查）分流，避免读者误入按主题分类的目录。✅ 已落地（首页「三个顶级入口」卡片 + 入口表）
/reference/core-map加"公式来源页"——把分散在各章的公式汇总成一页，每条公式链回原章节。
五、反模式清单
| 反模式 | 症状 | 修复 |
|---|---|---|
| 把教程和解释写在一起 | 同一页既讲"怎么跑"又讲"为什么"，读者卡住 | 拆成 tutorial 页和 explanation 节，互链 |
| 章节之间无前置依赖声明 | 跳到第7章才发现需要第5章的知识 | 每章页顶部加"先修章节" |
| 顶级目录按主题而非意图 | "模型 / 数据 / 训练" 三个 tab，读者不知道先点哪个 | 改为"学 / 做 / 查 / 懂"四个入口 |
| 同一术语多处定义 | "注意力"在 glossary 和讲义里定义不一致 | glossary 作为唯一定义源，其他处一律外链 |
| notebook 链接散落在讲义中段 | 读到一半被打断去找代码 | 实验统一进 /examples/，讲义里只放锚链接 |
| 评估与内容混杂 | quiz 题藏在讲义里、找答案要翻页 | 评估单独成页（如 /reference/graduation 的口试清单），讲义里只放锚链接 |
| 标题写成"第 X 章 X" | 无法跳读、无法搜索 | 改成问题或动作导向标题 |
参考来源
- Diátaxis 框架主页：https://diataxis.fr/（查阅日期 2026-08-10）
- Diátaxis Tutorial 定义页：https://diataxis.fr/tutorials/（查阅日期 2026-08-10）
- Diátaxis How-to Guides 定义页：https://diataxis.fr/how-to-guides/（查阅日期 2026-08-10）
- Diátaxis Reference 定义页：https://diataxis.fr/reference/（查阅日期 2026-08-10）
- Diátaxis Explanation 定义页：https://diataxis.fr/explanation/（查阅日期 2026-08-10）
- Karpathy
nn-zero-to-hero仓库目录：https://github.com/karpathy/nn-zero-to-hero（查阅日期 2026-08-10） - Karpathy 课程介绍页：https://karpathy.ai/zero-to-hero.html（查阅日期 2026-08-10）
- Andrew Ng 机器学习课程页：https://www.coursera.org/learn/machine-learning（查阅日期 2026-08-10）
- Google Developers ML 文档主页：https://developers.google.com/machine-learning（查阅日期 2026-08-10）
- Google Developers Style Guide：https://developers.google.com/style（查阅日期 2026-08-10）
- 3Blue1Brown 神经网络主题页：https://www.3blue1brown.com/topics/neural-networks（查阅日期 2026-08-10）