文档化管理是让每份文档可定位、可追溯、可协作、可复用，需结合结构化目录、语义化命名、Spotlight检索、Git版本控制及知识图谱沉淀。文档化管理不是把文件堆进文件夹，而是让每份文档可定位、可追溯、可协作、可复用。对 macOS 开发者来说，文档不只是说明书或笔记，它和代码、配置、数据一样，是开发资产的一部分。
结构化目录 + 语义化命名
统一根目录（如 ~/documents/projects），按项目隔离，每个项目内设标准子目录：code/（git 管理）、data/（标注 raw/processed）、docs/（markdown/pdf）、experiments/（临时草稿）。避免“新建文件夹(1)”“untitled”这类无意义名称。
文件名体现上下文：用 [项目缩写]_[用途]_[日期]_[环境].扩展名 格式，例如：
APIGATEWAY_auth_flow_20260615_v2.mdMLTRAIN_config_prod_20260610.yaml-
_tmp_debug_log_20260616.log（带_tmp_前缀，便于自动归档或清理）
元数据增强 + Spotlight 深度集成
macOS 自带的 Spotlight 是被低估的文档检索引擎。配合 Finder 标签和属性注释，能极大提升查找效率：
- 用颜色标签分类：红色=紧急待审，蓝色=技术规范，紫色=实验记录
- 给关键文档加 Finder 注释：
xattr -w com.apple.metadata:_kMDItemUserTags '["设计","待评审"]' design_spec.md - 用
mdfind组合搜索：mdfind 'kMDItemTextContent == "*OAuth*" && kMDItemFSName == "*.md"'
安装 QuickLook 插件（如 qlmarkdown、qlstephen）后，直接空格预览 Markdown、JSON、无扩展名配置文件，无需打开编辑器。
版本化文档 + 与代码协同演进
文档不该脱离代码生命周期。把 Docs/ 目录纳入 Git 仓库（或单独建 docs-repo），做到：
- 每次提交代码时，同步更新关联文档（如 API 变更 → 更新 OpenAPI YAML + 对应 README）
- 用 Git Tag 标记文档快照（如
v1.2-docs），与发布版本对齐 - 在 README 中嵌入自动生成的变更日志（借助
git log --oneline -n 5 docs/）
敏感内容（如含密钥的配置示例）不硬编码在文档中，改用占位符（YOUR_API_KEY_HERE）+ 单独的 .env.example 文件说明使用方式。
知识沉淀层：独立知识库而非散落笔记
项目文档解决“当下怎么做”，知识库解决“为什么这么做”和“类似问题怎么解”。建议用 Obsidian 或 Logseq 在 ~/Documents/KnowledgeBase/ 建立个人知识图谱：
- 每篇笔记以问题为标题（如 “如何在 M1 Mac 上调试 Rosetta 进程？”）
- 用双向链接串联相关技术点（如链接到
[[Apple Silicon]]、[[lldb]]） - 定期导出静态 HTML 备份，或用 GitHub Pages 公开非敏感部分
避免把知识库变成“收藏夹”。每条记录附上来源、验证时间、适用 macOS 版本（如 “tested on macOS 14.6, Xcode 15.4”），确保信息不过期。
