Design doc template / 设计文档模版讨论

[Fatman13]

着重借鉴了FIP的模版：这里。

Simple Summary (概述)

"If you can't explain it simply, you don't understand it well enough." Provide a simplified and layman-accessible explanation of the design.
俗话说："如果你不能以简单的话解释，说明你还不够懂他"提供一个简单的，非技术人员也能理解的介绍。

Abstract (功能简介)

A short (~200 word) description of the technical issue being addressed.
一个简短的200字以内的，描述当前的功能设计。

Motivation (来源/背景)

The motivation is critical for new feature design that want to change the product. It should clearly explain why the existing product specification is inadequate to address the problem that this new feature solves.
功能设计动机是很重要的。当前现有产品的哪儿些不足，功能需求的来源和背景，等等。在这个feature（设计）完成后，哪儿些问题会得到解决？

Specification (feature Spec)

The technical specification should describe the syntax and semantics of any new feature. The specification should be detailed enough to allow others to easily translate into product implementations.
具体的技术spec，需要对feature的syntax，semantics进行描述。Spec需要能够让别人更容易的按照spec去实现这个feature。

Design Rationale (设计思路)

The rationale fleshes out the specification by describing what motivated the design and why particular design decisions were made. It should describe alternate designs that were considered and related work.
设计思路基于上面的spec，描述了设计上的一些选择，以及为什么使用了这些选择。

Backwards Compatibility（兼容性）

All design/feature that introduce backwards incompatibilities must include a section describing these incompatibilities and their severity. The design/feature must explain how the author proposes to deal with these incompatibilities.
所有功能设计都需要包含向前兼容性问题的描述。如，有哪儿些和之前版本不兼容的地方，不兼容地方的严重性，等等。功能设计文档需要包含作者如何处理/解决这些不兼容问题。

Test Cases (测试用例)

Test cases for an implementation. Links to test cases if applicable.
测试用例，如果有的话。

Security Considerations (安全考量)

All design/feature must contain a section that discusses the security implications/considerations relevant to the proposed change. Include information that might be important for security discussions, surfaces risks and can be used throughout the life cycle of the proposal. E.g. include security-relevant design decisions, concerns, important discussions, implementation-specific guidance and pitfalls, an outline of threats and risks and how they are being addressed.
安全问题，如果有的话。

Implementation（实施）

Include any implementation details that you find may be helpful to elaborate your design. This may be a flow chart, an architecture diagram, system work flow chart.
任何有助于展示设计意图的图标，等等都可以添加在这里。