模板
本页是每类文档的骨架。开始写一篇文档时,把骨架复制到两种语言各一个新文件里。每个标题下面的那句话说明这里该写什么,写的时候替换掉它。不适用的章节保留,并用一行说明原因。
元数据字段的定义见文档体系。
能力页
能力页放在 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 的推论,并链接到状态文档。
## 参考
文章所依据的所有资料的链接。