文档工程从README到完整文档体系

当项目从单文件工具成长为一个有一定复杂度的系统时 文档需要分层

剑飞
1/14文档工程 从README到完整文档体系

一开始只有 README

01命题

先说清本页判断

02解释

补足为什么

03行动

留下下一步

把“一开始只有 REA”落到一个具体项目里看结果
2/14文档工程 从README到完整文档体系

README 是大多数用户

README 是大多数用户与一个项目的第一次接触
3/14文档工程 从README到完整文档体系

一个好的 README 应

01命题

先说清本页判断

02解释

补足为什么

03行动

留下下一步

把“一个好的 READ”落到一个具体项目里看结果
4/14文档工程 从README到完整文档体系

不要说"一个XXX框架"

命题先说清本页判断
解释补足为什么
行动留下下一步
把“不要说"一个XXX”落到一个具体项目里看结果
5/14文档工程 从README到完整文档体系

详细的API文档

README 里不应该有什么详细的API文档完整的配置说明 长篇的设计

把“详细的API文档”落到一个具体项目里看结果
6/14文档工程 从README到完整文档体系

当项目从单文件工具成长为一

当项目从单文件工具成长为一个有一定复杂度的系统时 文档需要分层

任务把能力放进真实场景
限制让标准和期限出现
结果用交付校准判断
7/14文档工程 从README到完整文档体系

这五层文档模型（快速入门

这五层文档模型（快速入门 概念指南操作指南 API参考解释性文章）来自 Divio 的文档
8/14文档工程 从README到完整文档体系

文档和代码一样

01命题

先说清本页判断

02解释

补足为什么

03行动

留下下一步

把“文档和代码一样”落到一个具体项目里看结果
9/14文档工程 从README到完整文档体系

和代码一样

命题先说清本页判断
解释补足为什么
行动留下下一步
把“和代码一样”落到一个具体项目里看结果
10/14文档工程 从README到完整文档体系

以一个实际的开源项目为例

以一个实际的开源项目为例看看文档是如何从一个烂 README 演进到完整文档体系的
11/14文档工程 从README到完整文档体系

可以跳过前三个阶段的痛苦

01命题

先说清本页判断

02解释

补足为什么

03行动

留下下一步

把“可以跳过前三个阶段”落到一个具体项目里看结果
12/14文档工程 从README到完整文档体系

带走四步

找项目

从真实任务开始

出材料

把想法变成可处理内容

做交付

用结果判断能力

可复用

把完成沉淀为流程

13/14文档工程 从README到完整文档体系

让能力长出来

当项目从单文件工具成长为一个有一定复杂度的系统时 文档需要分层

返回原文
上一篇LAN worker租约边界下一篇队列自校正 已完成计划为什么还会停在队列里