上一篇把终端配置做成可迁移的 dotfiles本篇解决“命令会跑但没人知道为什么”的问题用 Obsidian、Logseq 管个人知识用 MkDocs、Docusaurus、VitePress 发布团队文档用 Diátaxis 区分教程、操作指南、解释与参考。一、痛点不是没写文档而是检索不到可信答案笔记常见三种失效按工具分类导致同一任务信息散落多处只记录成功命令没有前提、输出和回滚多份复制产生冲突却看不出哪份最新。个人笔记适合快速捕捉与双向链接团队文档需要审查、稳定 URL、责任人和更新触发器。把两者强行塞进同一工具往往既降低记录速度也模糊发布责任。Obsidian 以本地 Markdown 和插件生态见长Logseq 强调大纲、块引用与日志式记录MkDocs 配置轻、适合技术文档Docusaurus 适合 React 生态、版本化和内容站点VitePress 与 Vue/Vite 集成自然。选择时先检查数据能否导出、链接是否为普通文本、离线是否可用、插件停更后内容是否仍可读。格式寿命通常比功能数量重要。二、原理按读者任务组织而不是按作者记忆组织Diátaxis 的四象限很实用教程帮助新人完成第一次成功操作指南解决明确任务解释说明原理与取舍参考提供精确事实。一个页面混合四种意图时读者既找不到快速步骤也看不清边界。每页还应有标题、目标读者、前置条件、验证方式和最后复核日期。链接是知识库的接口。稳定文件名、相对链接和明确锚点能被静态检查“点这里”无法脱离上下文理解。决策记录使用 ADR背景、决策、备选方案、后果、状态。它不追求还原所有讨论而是解释为什么今天的代码长这样。下面脚本只用标准库扫描一组内存文档建立反向链接并找出孤立页面。真实项目可将pages替换为读取 Markdown 文件的结果思路仍然适用。importrefromcollectionsimportdefaultdict pages{index:从 [[setup]] 开始设计理由见 [[adr-001]]。,setup:安装后按 [[runbook]] 验证。,runbook:故障时回到 [[index]] 查看入口。,adr-001:本决策采用纯 Markdown。,draft:尚未接入导航的草稿。,}backlinksdefaultdict(set)broken[]forsource,contentinpages.items():targetsre.findall(r\[\[([^]])\]\],content)fortargetintargets:iftargetinpages:backlinks[target].add(source)else:broken.append((source,target))reachable{index}queue[index]whilequeue:currentqueue.pop(0)fortargetinre.findall(r\[\[([^]])\]\],pages[current]):iftargetinpagesandtargetnotinreachable:reachable.add(target)queue.append(target)orphanssorted(set(pages)-reachable)print(fpages{len(pages)})print(fbacklinks_to_index{,.join(sorted(backlinks[index]))})print(fbroken{len(broken)})print(forphans{,.join(orphans)})运行输出pages5 backlinks_to_indexrunbook broken0 orphansdraft孤立页不一定应删除可能是尚未发布的草稿但它必须有状态不能静默消失在目录深处。三、实现搭建可验证的 Markdown 文档库先定义目录docs/tutorials、docs/how-to、docs/explanation、docs/reference与docs/adr。导航只呈现成熟入口草稿通过 front-matter 标状态。代码示例应能从仓库执行而不是复制后依赖作者电脑。以下脚本创建临时文档站检查相对链接、禁止标题跳级并输出页面统计它只依赖 Bash 和 Python 3。#!/usr/bin/env bashset-euopipefailsite$(mktemp-d)cleanup(){rm-rf$site}trapcleanup EXITmkdir-p$site/docs/how-to$site/docs/referenceprintf%s\n# 文档入口- [运行服务](how-to/run.md)$site/docs/index.mdprintf%s\n# 运行服务执行 make run再访问健康检查。$site/docs/how-to/run.mdprintf%s\n# 配置参考所有环境变量必须有默认行为说明。$site/docs/reference/config.mdpython3 -$site/docsPY import pathlib import re import sys root pathlib.Path(sys.argv[1]) pages list(root.rglob(*.md)) broken [] for page in pages: text page.read_text(encodingutf-8) levels [len(m.group(1)) for m in re.finditer(r^(#) , text, re.M)] assert all(b - a 1 for a, b in zip(levels, levels[1:])), page for target in re.findall(r\[[^]]\]\(([^)#]), text): if not (page.parent / target).resolve().exists(): broken.append(f{page}:{target}) assert not broken, broken print(fpages{len(pages)} broken_links0) PYprintfstatusok\n接入 MkDocs 后在 CI 运行严格构建和链接检查外链可定期检查但要设置超时与重试避免第三方短暂不可用阻断每次提交。截图只用于视觉信息命令与错误消息保持文本便于复制、搜索与无障碍阅读。会议笔记在 24 小时内提炼行动项进入任务系统长期决策进入 ADR可复用步骤进入操作指南其余上下文留在日志。这样笔记不是任务管理器的替代品。涉及客户、凭证和内部地址时先分级公开文档库不能因为“Markdown 是本地文件”就放松权限。每个操作指南最好包含可观察的终点。例如“部署成功”应写成版本端点返回目标提交、核心探针通过、错误率在阈值内而不是“页面能打开”。命令前标注执行目录和权限命令后给出关键输出及异常分支具有副作用的步骤说明备份与回滚。版本升级时从这些指南抽取冒烟测试文档因此成为可执行验收的来源而非发布完成后的装饰。知识库需要明确生命周期。草稿有作者和到期日已验证页面记录适用版本废弃页面保留短期重定向并指向替代内容。代码所有者可以同时负责相邻文档评审模板要求检查接口、配置和截图是否变化。对于跨团队概念建立一个权威定义页其余页面链接它而不是复制定义。减少复制比依赖“全文搜索找最新版”可靠得多。四、踩坑双向链接不能替代信息架构随意创建标签会产生同义词例如“API”“接口”“后端接口”各自成岛。维护一小份受控词表页面标题使用读者会搜索的任务语言。大量插件会把内容写成专有语法迁移时只剩不可读标记关键资料坚持 CommonMark、普通图片与标准 front-matter。另一个陷阱是自动生成文档无人复核。API 参考可以生成但教程、错误解释与迁移指南仍需写清上下文。文档最后更新时间也不等于正确最好把变更触发器写进代码评审清单改环境变量、接口、运维步骤时必须同步对应页面。五、验证让陌生读者完成任务选择一位没参与实现的人给他文档入口和一个任务从零启动服务、触发健康检查、定位一个配置项并回滚。记录卡住的位置而不是现场口头补充。自动验收则覆盖站点严格构建、内部链接、标题层级、示例命令和敏感信息扫描。搜索日志中长期无结果或高频无点击的关键词是下一轮补文档的真实需求。本篇把前五篇的操作沉淀成可检索资产。下一篇将这些文档中的重复步骤转成开源自动化用 Make、just、Task、Ansible 与 pre-commit 编排任务同时保证幂等、dry-run 和失败可见。参考来源Diátaxis官方方法说明Obsidian官方帮助MkDocs官方文档Architecture Decision Records项目资料 觉得有用就点个赞 收藏方便回头查阅有疑问直接在评论区留言我看到都会回。 本文属于《海外开发者神器盘点》系列持续更新关注不迷路。 文章里的代码都能直接跑。想要可直接 clone 的完整工程 配套部署脚本 / 踩坑清单评论一声或发邮件到cj2664qq.com我免费发你。如果你正好在做类似系统、或有工程化难题想找人做也欢迎邮件聊一句——我按实际情况评估能落地的就接单或出方案。评论和邮件都能直接找到我不用跳别的平台。