文档体系
本页规定 cotty 的文档如何组织、每类文档包含什么,以及让文档保持最新的规则。本页是规范性描述,为什么这样定见 RFC 0001。
两类文档
文档会过时失效,是因为一页里混了两种时间语义。这里的每篇文档都属于下面两类之一:
- 状态文档描述现在是什么。它只有一份,永远是当前的,可以随时重写。
- 事件文档记录某个时点提出、决定或发现了什么。它带日期。被接受或写完之后不再改写,后来的事件另写一篇放在旁边。
文档还分属两个空间:问题空间(为什么、做什么)和方案空间(怎么做)。
| 状态:一份,永远当前 | 事件:带日期,只追加 | |
|---|---|---|
| 问题空间 | 产品设计 | 版本设计、调研 |
| 方案空间 | 架构、规范 | RFC |
| 面向外部读者 | 规范 | 文章 |
规则
- 折叠。 事件文档讲为什么改。改动本身写进状态文档,并且在同一次提交里。一篇 RFC 或版本设计,只有在它影响的状态文档都更新之后,才算被接受。
- 一个归属。 每个事实只在一页里陈述。其他页面链接过去,不复述。
- 事件不改写,状态不写历史。 事件文档被接受后,只改状态和明显的笔误。状态文档描述现在。它的元数据列出影响过它的 RFC,除此之外不谈过去。
- 已设计不等于已实现。 状态文档描述已接受的设计。页面记录实现它的版本。在那之前它只是设计。
文档放在哪里
docs/
├── en/ 英文,规范文本
│ ├── product/ 产品设计 状态
│ ├── versions/ 每个版本一篇设计 事件
│ ├── architecture/ 内部技术设计 状态
│ ├── specs/ 协议、格式、API 状态
│ ├── rfcs/ 技术决定 事件
│ ├── research/ landscape/、studies/、field-notes/ 事件
│ ├── posts/ 文章 事件
│ └── handbook/ 项目如何运作 状态
└── zh/ 中文译文,路径相同
site/ Hugo 项目:配置和模板
tools/ 检查脚本
文档的类别由所在目录决定。页面不自己声明类别。
docs/ 里的所有内容都发布到站点上。
各类文档
每类文档的骨架见模板。
产品设计
产品设计回答产品为什么存在、做什么。它放在 product/,由一组页面构成:
| 页面 | 内容 |
|---|---|
| 定位 | 要解决的问题、谁有这个问题、为什么是现在、cotty 是什么、为什么它的几部分是一个设计、它坚持什么、不做什么。讲问题和产品,不讲市场和竞争。只写我们自己的思考,不点名其他产品。对其他产品的分析放在调研里。 |
| 场景 | 少量用户角色和核心场景,写成具体的故事。每个场景有编号,并链接到证据。版本设计和 RFC 引用场景编号。 |
| 原则 | 遇到取舍时怎么选。每条原则配一个例子。 |
| 概念模型 | 用户看得见的对象,以及它们的关系和状态。产品文档和技术文档共用这套词。 |
| 能力页 | 每个能力一页:问题、写成可检验陈述的行为、状态、界面、不在范围内的事。 |
| 质量标准 | 延迟预算、兼容性、隐私承诺。 |
| 路线图 | 现在、下一步、以后。 |
一个页面在内容设计出来之后才添加。设计达成一致之前状态是 draft,之后是 accepted。
版本设计
版本设计说明下一个版本在产品上改什么、为什么改。它放在 versions/,文件名是 vX.Y.md。它列出的场景同时是验收脚本。状态依次是 planning、active、shipped。已发布的版本设计冻结不改。
产品设计通过版本设计来改。技术设计通过 RFC 来改。
架构
架构页描述 cotty 内部怎么构成:组件、数据、不变量、故障与恢复。它们放在 architecture/。项目之外没有东西依赖它们,所以只要有 RFC 就可以改。
规范
规范是 cotty 和其他程序之间的约定:协议、格式、API。它们放在 specs/。读者是在别处实现它们的人,比如 agent CLI 和其他终端的作者。
RFC
一篇 RFC 记录一个技术决定。见 RFC 流程。
调研
调研记录截至某个日期关于外部世界的事实。它放在 research/,分三个目录:
landscape/:这个领域里的产品和项目。studies/:一个问题,调查一次。field-notes/:真实使用中发生了什么。
调研从不具有规范效力。每篇都写明事实的核对日期,列出来源,并标注每条说法的可靠性:官方、厂商或第三方。结尾写这些发现对 cotty 意味着什么。更新时写一篇新的。旧的保留,并加一行指向新的那篇。
调研是发布的,这样读者可以核对状态文档的依据。由此有两条规则:
- 写其他项目的笔记只做描述,并写明来源。下判断的地方,要说明这是判断。
- 实地记录里的机器和人用代称。不写地址,不写密钥。
文章
文章是写给外部读者的。它们放在 posts/。文章解释我们怎么想,不做决定。决定留在状态文档和 RFC 里。
调研和文章的区别在于价值来自哪里。价值在事实的,是调研:事实带日期和来源,由更新的一篇笔记来刷新。价值在论证的,是文章:它用我们自己的口吻写,事实部分引用调研。
手册
手册说明项目如何运作。本页属于手册。
语言
- 每个页面都有英文和中文两版,分别在
docs/en和docs/zh下的相同路径。两版在同一次提交里添加和修改。 - 英文是规范文本。中文是它的译文。两者不一致时以英文为准,并把不一致当作缺陷修掉。
- 同一页面的两版,除
title外元数据相同,标题结构相同,代码块数量相同,链接指向相同的页面。
约定
语气
每个页面都会发布,所以每个页面都是写给项目之外的读者的。
- 说清楚这个东西是什么、怎么工作、为什么这样做。写明它的限制,也写明哪些还没有决定。
- 用平实的词。不用销售和竞争的话术:卖点、护城河、赢、谁抄谁。
- 写 cotty 的页面讲的是问题和产品。其他产品放在调研里如实描述。
元数据
每个页面以一个元数据块开头。它只用 YAML 的一个小子集:key: value 行,以及由普通值构成的列表。
| 字段 | 用在哪里 | 含义 |
|---|---|---|
title |
所有页面 | 页面标题。 |
created |
除目录页外的所有页面 | 页面首次写成的日期,格式 YYYY-MM-DD。 |
status |
product、architecture、specs、handbook | draft 或 accepted。 |
status |
versions | planning、active 或 shipped。 |
status |
rfcs | 见 RFC 流程。 |
rfc |
rfcs | RFC 编号。 |
affects |
rfcs | 这篇 RFC 改动的状态页面,写语言目录之下的路径。 |
rfcs |
状态页面 | 改动过本页的 RFC 的编号。 |
implemented |
状态页面,可选 | 实现本页的版本。 |
as_of |
research | 事实的核对日期。 |
supersedes、superseded_by |
rfcs,可选 | 被取代的、或取代它的 RFC 的编号。 |
authors |
可选 | 姓名列表。 |
weight |
可选 | 页面在所属目录里的排序位置。 |
页面最后修改的日期不存在页面里,它来自版本历史。
标题
标题写在元数据里。正文没有一级标题,直接以文字或二级标题开始。
链接
页面之间的链接写成指向 .md 文件的相对路径,用行内形式。这样的链接在代码仓库的浏览界面里和在站点上都能用。锚点用同一语言里标题的锚点。
目录页
每个目录有一个名为 _index.md 的入口页。这个名字是站点生成器要求的。
文件名
文件名用小写字母和连字符。
| 类别 | 名称 |
|---|---|
| RFC | NNNN-slug.md,四位数字 |
| 调研 | YYYY-MM-slug.md |
| 版本设计 | vX.Y.md |
图
图用 mermaid 写,放在 mermaid 代码块里。代码仓库的浏览界面会把它画出来,站点也会。mermaid 表达不了的图,用放在 text 代码块里的纯文本,或者一个 SVG 文件,并和生成它的源文件一起提交。
检查
tools/check.py 只使用 Python 标准库。make check 运行对源文件和样式表的检查。make verify 还会构建站点并检查结果。
对源文件的检查:
- 每个页面两种语言都有。
- 元数据格式正确,每类文档具备它要求的字段和状态值。
- RFC 编号唯一,并且和文件名一致。
- 同一页面的两版在元数据、标题结构、代码块和链接目标上一致。
- 页面之间的每个链接都指向存在的文件。
- 正文里没有一级标题。
- 已接受的 RFC 列出它影响的页面,这些页面也都列出这篇 RFC。
对构建出的站点的检查:
- 页面之间的每个链接都能解析到一个页面。
- 这些链接里的每个锚点在目标页面上都存在。
- 没有页面从其他主机加载脚本、样式表或图片。
- 每个脚本都是由站点自己提供的文件。每个页面里的结构化数据是数据而不是脚本,它必须格式正确。
对样式表的检查:
- 每个颜色在两个主题里都达到站点设计对它要求的对比度。
- 样式表里的颜色和那一页色板表里的颜色一致。
站点
站点用 Hugo 构建。Hugo 是单个程序,版本固定在 mise.toml 里。模板、样式表和搜索脚本都在 site/ 里,是为本项目写的。没有第三方主题。站点的样子由站点设计规定。
站点由 GitHub Pages 发布在 https://nowa.im/cotty/,英文在根路径,中文在 /zh/ 下。每次推送都有一个工作流运行检查,并发布 main 分支。一个栏目在有了页面之后才出现在导航里。
三条规则让构建链保持很小:
- 构建不通过包管理器安装任何东西。
- 页面不从其他主机加载任何东西。
- 页面上可以用 JavaScript,并且由本项目自己编写。来自别处的代码,只能以保存在仓库里的副本形式加入,它的版本和来源记录在
site/VENDORED.md里。每一份这样的副本都是由维护者批准的例外。目前有一份:用来画图的 mermaid。
搜索在浏览器里运行。Hugo 为每种语言生成一份所有页面的索引,site/assets/js/search.js 用查询去匹配它。
面向搜索引擎,每个页面都带有描述、规范地址、指向另一种语言的链接和结构化数据,站点有站点地图。面向语言模型,站点有 llms.txt(页面索引)和 llms-full.txt(全文)。每个页面还以 Markdown 形式发布,地址是页面地址后面加 index.md。
尚未决定
- 文档的许可协议。