Apple 文档全史：从 Woz 的笔记到 DocC 与 Xcode 智能代理

两条原则一直并行：面向普通用户的产品不应要求先读厚手册才能完成基本任务，而开发者平台如果没有深入、精确、持续维护的技术文档就无法扩展。Apple 最有价值的做法，是把“解释不清楚”当成界面或 API 设计可能有问题的信号。 [A19][A21][A5][A4]

研究快照为 2026 年 8 月 17 日，优先使用原始手册、Apple Times、Computer History Museum 口述史、Macintosh 团队一手回忆、Steve Jobs Archive 以及当前 Apple 和 Swift 官方文档。没有可靠直接引语时不补造观点。 [A1][A3][A4][A5][A7][A10][A13][A14][A19][A2]

Apple-1 面向技术爱好者，少量操作说明和电路图尚能满足需求。Apple II 扩大了受众后，内存、视频、I/O、ROM 和扩展机制必须从工程师个人知识转化为他人可以独立查阅的材料。 [A1][A2]

没有找到 Wozniak 宣称“文档是一切”的可靠宣言。更有价值的证据是他的技术笔记和后来的 Apple II Reference Manual：机器的架构被解释到第三方可以编程和扩展的深度。 [A1][A2]

Chris Espinosa 回忆，Publications Style Guide 规定了如何解释 human interface。为了让解释保持一致，应用本身也必须表现一致，于是文档规范逐渐成为设计治理工具。 [A4]

Apple Times 记录了 document design、alpha、beta 和 final 四个阶段。Beta 会交给代表目标用户的外部读者，反馈不仅修改手册，也可能修改产品。 [A3]

1982 年文本可从 Pascal 文件经过 Script、Qume、Compugraphic，再与照片和插图做实体 paste-up。1984 年 Macintosh 已能用 Command-Shift-3 把屏幕保存成 MacPaint 文档，Susan Kare 也在 MacPaint 中为手册作画，但印前环节仍可能使用剪刀和胶水。 [A3][A7][A8][A6]

1982 年 Apple Times 已讨论让用户直接在电脑上学习基本操作，把纸质手册留给更深入的内容。也就是说，onboarding 与 reference 的分离早于 Web。 [A3]

1984 年 Jobs 嘲讽 400 页 WordStar 手册，2007 年又用“功能藏在没人读的手册第 93 页”说明同一问题。他反对的是普通功能缺乏可发现性，而不是反对所有技术文档。 [A21][A19][A5]

Macintosh 手册必须从零解释 pointer、click、drag、icon、window、menu 和 Trash。手、鼠标的线描图与界面位图把身体动作和屏幕反馈连接起来。 [A7]

Andy Hertzfeld 认为开发者文档对 Macintosh 成功至关重要。Caroline Rose 对参数和边界条件的精确追问会暴露不清晰的契约，有时甚至促使工程师先修改 API，再继续写文档。 [A5]

Human Interface Guidelines 把交互行为变成第三方应用可以共同遵守的规则。从早期 Publications Style Guide、1992 HIG 到 2026 Apple Style Guide，术语、UI 文案和交互设计始终相互连接。 [A4][A9][A24][A10]

随着平台变大，“找到正确文档”与“写出文档”同样重要。Developer Library 和 Xcode Documentation Organizer 按 framework、类型和主题组织 guides、reference 与 sample code，Quick Help 则把符号参考带进代码编辑器。 [A12]

Documentation Archive 显示旧 guide 是逐步退役的。保留旧文档有助于重现历史开发环境，但 retired 状态、日期和后继文档必须明显，否则历史内容会继续被误当成当前建议。 [A11][A22][A23]

Swift-DocC 将 API 注释、Markdown 长文和 tutorials 合在一个系统中。Apple 先为内部 SDK 文档开发它，再集成进 Xcode 并开源，使链接和结构可以在 build 中验证。 [A14][A15][A3]

当前 Apple 文档为自动化与辅助工具提供 Markdown，Xcode coding agents 也能在执行任务时搜索官方文档。同一知识库现在需要同时服务人、IDE 上下文和 agent。 [A13][A16][A17][A18]

Susan Prescott 把 Developer Relations 的目标表述为给开发者更好的工具并降低工作流摩擦。Apple 很少把“文档”单独宣传，因为 reference、samples、diagnostics、tutorials 与 agent context 已嵌入完整 developer experience。 [A17][A18]

从 Publications Style Guide 到 2026 Apple Style Guide，Apple 一直要求 documentation、reference、training 和 user interfaces 使用一致语言。术语一致性被当作产品属性，而不仅是文字润色。 [A4][A9][A10]

文档始终靠近工程：写作者能影响 API，HIG 能影响应用，DocC 与代码同库，Xcode 在工作现场提供 reference。Apple 也长期区分 onboarding、concept、reference 和 examples。 [A5][A9][A12][A14]

完整的 symbol reference 并不总能替代旧 Programming Guides 的架构叙事。老档案在搜索中可能长期占据高位，若过度为机器读取优化，内容也可能被切得过碎而损害人的理解。 [A11][A13]

把写作当成产品测试，分开首次成功路径与深入 reference，尽早统一术语，把 docs 放进工程工作流，清晰标记档案状态，并用一个知识模型同时服务人、IDE 和 agent。 [A5][A10][A11][A14][A17]

Apple 老手册说明，不同图形回答不同问题：电路图解释结构，线描解释身体动作，截图证明状态，HIG 图解释预期行为。截图制作便宜了，但后续维护成本从未消失。 [A1][A7][A9]

Apple 从工程笔记走到经过用户测试的手册、能推动 API 修改的技术写作者、界面规范、Xcode 集成、DocC 与可被 agent 读取的 Markdown。真正的变化不是从纸到 HTML，而是文档不断靠近产品生命周期。 [A5][A19][A21]