本页内容
  1. 两类文档
  2. 规则
  3. 文档放在哪里
  4. 各类文档
  5. 产品设计
  6. 版本设计
  7. 架构
  8. 规范
  9. RFC
  10. 调研
  11. 文章
  12. 手册
  13. 语言
  14. 约定
  15. 语气
  16. 元数据
  17. 标题
  18. 链接
  19. 目录页
  20. 文件名
  21. 图
  22. 检查
  23. 站点
  24. 尚未决定

本页规定 cotty 的文档如何组织、每类文档包含什么,以及让文档保持最新的规则。本页是规范性描述,为什么这样定见 RFC 0001。

两类文档

文档会过时失效,是因为一页里混了两种时间语义。这里的每篇文档都属于下面两类之一:

  • 状态文档描述现在是什么。它只有一份,永远是当前的,可以随时重写。
  • 事件文档记录某个时点提出、决定或发现了什么。它带日期。被接受或写完之后不再改写,后来的事件另写一篇放在旁边。

文档还分属两个空间:问题空间(为什么、做什么)和方案空间(怎么做)。

状态:一份,永远当前 事件:带日期,只追加
问题空间 产品设计 版本设计、调研
方案空间 架构、规范 RFC
面向外部读者 规范 文章

规则

  1. 折叠。 事件文档讲为什么改。改动本身写进状态文档,并且在同一次提交里。一篇 RFC 或版本设计,只有在它影响的状态文档都更新之后,才算被接受。
  2. 一个归属。 每个事实只在一页里陈述。其他页面链接过去,不复述。
  3. 事件不改写,状态不写历史。 事件文档被接受后,只改状态和明显的笔误。状态文档描述现在。它的元数据列出影响过它的 RFC,除此之外不谈过去。
  4. 已设计不等于已实现。 状态文档描述已接受的设计。页面记录实现它的版本。在那之前它只是设计。

文档放在哪里

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。

尚未决定

  • 文档的许可协议。