本页内容
  1. 能力页
  2. 版本设计
  3. RFC
  4. 规范页
  5. 架构页
  6. 调研
  7. 文章

本页是每类文档的骨架。开始写一篇文档时,把骨架复制到两种语言各一个新文件里。每个标题下面的那句话说明这里该写什么,写的时候替换掉它。不适用的章节保留,并用一行说明原因。

元数据字段的定义见文档体系。

能力页

能力页放在 product/。它从用户的角度描述产品做的一件事。

---
title: 能力的名称
status: draft
created: YYYY-MM-DD
---

一段话:这个能力是什么,为谁服务。

## 问题与证据

现在哪里有问题,并链接到调研和实地记录。

## 场景

这个能力服务的场景,写编号。

## 行为

写成可以检验的陈述的规则。每条规则配一个例子。

## 状态

对象会经历哪些状态,什么引起每次变化。

## 界面

用户在每种设备上看到什么、做什么。

## 不在范围内

这个能力不做什么。

## 依赖

它依赖的内核能力,并链接到架构和规范。

## 待决问题

还没有决定的事。

版本设计

版本设计放在 versions/。

---
title: vX.Y
status: planning
created: YYYY-MM-DD
---

一句话:这个版本的主题。

## 场景

这个版本之后必须成立的场景。它们同时是验收脚本。

## 做与不做

这个版本做什么,以及有意不做什么。

## 对产品设计的改动

逐条列出改动,并链接到被改动的产品页面。

## 技术工作

这个版本需要的 RFC。

## 风险与待决问题

可能出什么问题,以及还没有决定的事。

## 完成标准

怎样算这个版本做完了。

## 回顾

发布之后写:和计划有什么不同,学到了什么。

RFC

RFC 放在 rfcs/。流程见 RFC 流程。

---
title: 这个决定的简短名称
rfc: 0
status: draft
created: YYYY-MM-DD
affects:
  - specs/example.md
---

## 摘要

一段话:提议什么。

## 动机

它服务的场景、证据,以及不做会怎样。

## 目标与非目标

这个决定必须达到什么,以及不打算达到什么。

## 已有做法

别人怎么做。链接到调研,不复述。

## 方案

思路、关键的不变量,以及一两个例子。确切的条文在受影响的页面里。

## 考虑过的备选方案

每个备选方案,以及没有选它的原因。

## 兼容性与迁移

哪些已有的行为、数据或文档受影响,它们怎么过渡。

## 安全与隐私

这个决定暴露了什么,保护了什么。

## 缺点与风险

代价是什么,可能出什么问题。

## 验证

怎样知道它是正确的。

## 待决问题

接受之前必须为空,或者每个问题都写明理由后延期。

## 实施

工作的顺序,以及要先读的页面和文件。

规范页

规范页放在 specs/。它是写给在项目之外实现它的人看的。它用"必须"、“应当”、“可以"来表述要求。

---
title: 协议、格式或 API 的名称
status: draft
created: YYYY-MM-DD
---

一段话:这里规定的是什么,由谁来实现。

## 稳定性与版本

它是实验性的还是稳定的,以及它的版本。只有稳定的部分有兼容性承诺。

## 现状的问题

现在做不到什么,或者做得不好的地方。

## 快速上手

一个照着就能运行的例子。

## 术语与不变量

本页使用的词,以及始终成立的事。

## 格式与语义

确切的格式,以及每个部分的含义。

## 探测与退化

程序如何得知是否支持它,以及不支持时会怎样。

## 与现有协议的关系

它和终端、agent 已经在用的东西如何配合。

## 安全考虑

攻击者能做什么,什么限制了他。

## 例子与测试向量

输入和它们应有的结果。

## 已知实现

实现了它的程序。

架构页

架构页放在 architecture/。

---
title: 组件或机制的名称
status: draft
created: YYYY-MM-DD
---

一段话:这个部分做什么,处在什么位置。

## 兼容性政策

什么必须保持可用,什么可以破坏。

## 目标与非目标

这个部分必须达到什么,以及不打算达到什么。

## 概念与不变量

涉及的对象,以及始终成立的事。

## 执行轨迹

主要路径的逐步轨迹,包括可能崩溃的位置,以及恢复如何进行。

## 接口与实现

这个部分提供的接口,以及它是怎么构成的。

## 待决问题

还没有决定的事。

## 测试策略

如何检验正确性。

## 必读清单

在这个部分上工作之前要读的页面和文件,按顺序列出。

调研

调研放在 research/ 的某个目录里。

---
title: 要回答的问题,或调研的对象
created: YYYY-MM-DD
as_of: YYYY-MM-DD
---

一段话:问题是什么,简短的答案是什么。

## 发现

事实。每条说法标注可靠性:官方、厂商或第三方。

## 对 cotty 的含义

对产品设计或技术设计的影响。

## 来源

用到的所有资料的链接。

## 没有覆盖

没有看的部分。

文章

文章放在 posts/。

---
title: 要论证的观点,或文章的主题
created: YYYY-MM-DD
---

一段话:观点是什么,它为什么对 cotty 重要。

## 论证

每一步一节,用这一节的结论做标题。带日期的事实属于调研笔记,文章链接过去。

## 我们从中得到什么

对 cotty 的推论,并链接到状态文档。

## 参考

文章所依据的所有资料的链接。