（9421期）Diataxis Writing – 结构化技术文档写作框架

结构化技术文档写作框架 基于 Diátaxis 框架的文档写作指南，提供四种文档类型（教程/指南/参考/解释）的诊断、分类、模板与质量评估，提升技术文档专业度。 使用说明 核心用法 Diataxis-writing 是一套结构化技术文档写作框架，帮助用户根据 Diátaxis 理论将内容准确分类为四种类型：Tutorial（教程，面向学习）、How-to Guide（操作指南，面向任务）、Reference（参考，面向查阅）、Explanation（解释，面向理解）。使用时需先询问目标语言与输出方式（聊天/飞书/Markdown/GitHub 等），确认工具可用性后，通过「Diataxis Compass」诊断文档类型，选择对应模板与检查清单，完成写作后执行质量评估并输出。 显著优点 理论扎实：基于欧洲核子研究中心（CERN）工程师 David P. Roberto 提出的 Diátaxis 框架，被广泛采用于 Django、Kubernetes 等主流项目文档。 分类清晰：四象限模型（学习/工作 × 行动/认知）从根本上解决文档类型混淆问题，避免「教程里塞满 API 参考」等常见错误。 模板完整：提供 Tutorial/How-to/Reference/Explanation 的专用模板、检查清单及语言风格指南，降低写作决策成本。 输出灵活：支持聊天消息、飞书文档（MCP）、本地 Markdown、GitHub 仓库等多种输出方式，适配个人与团队协作场景。 质量闭环：内置功能质量（准确性、完整性、一致性等）与深度质量（流畅度、人性化、美感）双重评估框架。 潜在缺点与局限性 工具依赖：飞书、GitHub 等输出需额外配置 MCP 服务器，对用户环境有一定要求；脚本检测依赖 Python3 环境。 学习成本：Diátaxis 理论本身需要理解「四象限」逻辑，初学者可能需阅读参考文档才能准确分类。 框架刚性：严格区分四种类型可能导致文档拆散，小型项目或快速迭代场景下可能显得繁琐。 中文资料有限：理论官网为英文，部分术语（如 Explanation vs. Tutorial）在中文语境中边界较模糊。 适合人群 技术文档工程师、开发者体验（DX）团队 开源项目维护者需重构文档体系 企业内训或知识库建设负责人 希望从「堆砌信息」转向「结构化写作」的内容创作者 常规风险 类型误判：若未使用 Compass 诊断，可能将 How-to 写成 Tutorial，导致用户迷失在冗长步骤中。 工具配置泄露：飞书 MCP 配置若硬编码在脚本路径，存在路径信息暴露风险（建议用户自行保管 config 文件）。 输出失败未回退：若 MCP 调用失败，需确保有降级到本地 Markdown 或聊天输出的机制，避免内容丢失。 原始说明 Diataxis documentation framework practice guide. Provides diagnosis, classification, templates, and quality assessment for four documentation types (Tutorial...