nannahelper docs，给完全不会编程的人写一份不会跳步的教程
我刚开始学编程时，经常遇到一种教程。
第一段告诉你安装工具。
第二段让你运行命令。
第三段突然开始讨论依赖注入、异步运行时和生产环境架构。
作者可能没有恶意。
他只是忘了，自己已经学会太久了。
很多中文教程的问题不是内容错误，而是默认读者知道得太多。它们会说「配置一下环境变量」，却不解释环境变量是什么。会说「进入项目目录」，却没有告诉读者怎么确认自己现在在哪个目录。命令报错后，教程直接进入下一步，仿佛报错只是读者个人的品德问题。
我和身边同学刚开始接触编程时，走过很多这样的弯路。
于是我们总会冒出一句话。
如果有一份真正假定读者什么都不会的教程就好了。
nannahelper docs 就是从这句话开始的。
零基础不是少讲一点
有些教程把零基础理解成少讲理论，只给出可以复制的代码。
我觉得这还不够。
复制成功只能证明环境暂时愿意配合。读者不知道为什么这么做，也不知道失败时应该检查哪里。只要路径、系统或版本稍有不同，整套步骤就会立刻失效。
真正的零基础教程应该补上那些熟练开发者已经自动忽略的步骤。
为什么要学这个。
它解决什么问题。
运行命令前应该站在哪个目录。
成功时会看到什么。
失败时最可能出现什么。
接下来能用它做什么。
项目目前覆盖了超过二十个主题，从 Git、GitHub、Markdown、LaTeX 和 MkDocs，到 Java、Rust、R、MATLAB、Linux、LLM API 与常用办公工具。
内容跨度很大，这也意味着统一教学结构比单纯增加文章数量更重要。
我为新内容设计了一套固定骨架。
先解释学习动机，再给出最小可运行示例。随后解释关键概念，列出常见陷阱，最后安排一个读者可以独立完成的小练习。
理想情况下，一篇基础章节的核心内容应该能在十五分钟左右读完。
不是因为知识只能讲十五分钟。
而是初学者第一次接触一个概念时，需要的是一个可以完成的小台阶。把所有细节一次性堆上去，只会让人站在楼梯下面研究建筑结构。
现有章节还没有全部达到这套标准。有些内容已经很完整，有些仍然偏长，还有些主题需要补充练习和错误示例。
这也是项目继续完善的重点。
教程要告诉读者为什么
我不太喜欢只写「输入下面的命令」。
以 Git 为例。
如果一上来就让读者背 add、commit、push，Git 很快会变成一组意义不明的咒语。只要出现冲突，所有咒语都会失效。
我更希望先解释版本控制到底在保存什么。
工作区、暂存区和提交历史分别是什么。
为什么修改文件后不能直接认为它已经进入版本记录。
为什么 push 不是保存，而是把本地提交同步到远程。
这些解释不需要变成计算机科学教材。
生活化比喻、状态图和一个最小仓库就够了。关键是让读者建立一个能继续推理的模型，而不是记住一套只能在截图完全一致时使用的步骤。
每一节还会尽量告诉读者如何验证。
安装 Python 后运行哪个命令。
创建文件后应该看到什么。
启动本地服务器后浏览器打开哪个地址。
如果看到「command not found」，应该先检查 PATH，还是检查虚拟环境。
学习编程最让人无助的时刻，往往不是不会写代码。
而是不知道自己现在做对了没有。
我为什么最后选择 MkDocs
开始搭建文档站时，我比较过 Docusaurus、VuePress、GitBook 和 MkDocs。
它们都能完成任务。
Docusaurus 的生态和 React 扩展能力很强，适合内容规模较大、交互需求较多的文档平台。但对这个项目来说，它的 Node.js 工具链和前端配置显得有些重。
VuePress 与中文开发者生态很接近，Vue 组件扩展也很灵活。不过我不希望教程维护者为了改一篇 Markdown，还要理解前端框架和构建细节。
GitBook 的编辑体验很好，协作门槛也低，但我更希望所有内容、配置和部署流程都完整留在 GitHub 仓库里。
最后选择了 MkDocs 加 Material 主题。
原因很直接。
配置集中在一个 YAML 文件里。
内容就是 Markdown。
本地预览只需要 mkdocs serve。
构建速度快。
Material 主题默认就拥有不错的导航、搜索、代码块、提示框和响应式体验。
更重要的是，教程本身的技术栈也应该符合教程的价值观。
如果一个面向初学者的文档项目，维护它却需要先掌握复杂的前端工程，我会觉得这件事有一点黑色幽默。
自动部署本身也是教学内容
文档站通过 GitHub Actions 自动构建和部署。
每次内容被合并到主分支，工作流会重新构建 MkDocs 站点，再发布到 GitHub Pages。维护者不需要登录服务器，也不需要手动上传生成文件。
提交前还可以执行引用检查、粗体格式检查和 mkdocs build --strict。
严格构建很重要。
普通构建可能会把警告打印出来后继续成功。严格模式会把部分警告当作错误处理。导航里写错文件名、文档引用不存在、配置不完整，这些问题应该在合并前暴露，而不是等读者点开链接时才发现。
我很喜欢把这套流程直接展示给读者。
教程不只讲 GitHub Actions 是什么。
教程仓库自己就在使用 GitHub Actions。
读者提交一个修正，CI 开始运行。合并完成后，网站自动更新。抽象概念立刻变成了可以观察的真实过程。
这比单独写一段「CI/CD 可以提高效率」更有说服力。
开放 PR 不代表放弃质量控制
项目放在 GitHub 上，任何人都可以通过 Issue 指出问题，也可以提交 PR 修改内容。
但开放协作不等于所有内容自动合并。
文档错误有时比代码错误更难发现。代码至少可能在运行时失败，错误解释却可以语法通顺地存在很久。
所以每个 PR 都需要经过自动检查和人工 Review。
自动化负责检查可以机械判断的内容。
文件引用是否存在。
MkDocs 能否严格构建。
格式是否符合约定。
人工 Review 负责判断更难量化的部分。
概念是否准确。
示例是否真的适合初学者。
步骤有没有跳跃。
比喻是在帮助理解，还是制造了新的误解。
一个 PR 最好只处理一件事。新增教程时，还需要同步更新导航、README 和分类页面。文件重命名后必须全局搜索旧引用，避免留下悄悄失效的链接。
这些规则看起来有些严格。
但教程面对的是不知道哪里出了问题的初学者。维护者多检查一次，读者可能就少怀疑自己一次。
公开一个还不完整的项目
我当然可以等所有章节都写完、所有截图都补齐、所有格式都统一之后再公开。
问题是，那一天很可能永远不会来。
教程项目没有真正的完成状态。工具会更新，界面会改变，旧命令会失效，读者又会提出维护者从未想到的问题。
所以我选择 Build in Public。
有些章节已经足够完整，可以直接帮助读者。有些章节仍然需要扩充，有些教程的结构还需要重新整理。我不打算用「持续更新」四个字掩盖这些不足。
它目前就是一个仍在建设中的项目。
公开它，是希望有人读到后觉得有用，也希望有人发现错误时愿意开一个 Issue。哪怕只是修正一个路径、补充一张截图、指出一句解释太跳跃，都可能让后来的读者少卡半小时。
我不是因为最懂这些内容才写教程。
很多时候，正是因为我刚刚踩过坑，还记得那个坑长什么样，才更适合把它写下来。
等一个人熟练到所有操作都变成本能之后，他反而很难想起初学者会在哪里停住。
nannahelper docs 想保留的，就是这种还没有忘记困难的视角。
我踩过这些坑。
希望下一个人可以少踩一遍。